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PREFACE 
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The CYBER 18/1700 File Manager is a general purpose file management system consisting of a resi- 
dent supervisor (operating under MSOS Version 5) and a set of mass storage resident request processors. 

The system allows definition of variable- or fixed-length records. Records may be stored sequen- 
tially, by key values (indexes), or to specific locations on mass storage previously assigned by the 
File Manager. Records may be retrieved (for use in updating, or to be removed from the file) sequen- 
tially, by use of key values, or from a specific location on mass storage previously assigned by the 
File Manager. 

File Manager space is predefined (at system initialization) and cannot be expanded or diminished. 
Space released by removal of records or files remains available to the File Manager for assignment 
of new files. 

It is assumed that users of this manual are familiar with CYBER 18/1700 MSOS 5. 

The following CYBER 18/1700 manuals contain additional information useful to File Manager users: 

Publication Publication No. 
MSOS 5 Reference Manual 96769400 

Mass Storage FORTRAN Version 3A/B Reference Manual 60362000 

Macro Assembler Reference Manual 60361900 
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INTRODUCTION 






The CYBER 18/1700 File Manager is a general-purpose file management package consisting of a 
request supervisor and a collection of request processors. The supervisor (FILMGR) resides in core; 
the request processors reside on mass storage. Core requirements are minimized by bringing in 
individual request processors only as they are needed. 

The File Manager creates and maintains either sequential or indexed files. Records in indexed files 
may be index-ordered (i.e. , numerically ordered within the index) or index-linked (i.e., several 
records may have the same key value). Also, the user may define additional methods of linking (e.g., 
ring indexed). Records in some files may be variable in length and may be added, replaced, or removed 
at any time after the file has been defined and before it is released. Other files (i.e. , index-linked) 
must have uniform-length records. 

A sequential file is one in which each new record is added immediately following the last record 
stored in the file. These records must be retrieved in the same sequence in which they were stored; 
records cannot be retrieved at random. Thus, they are retrieved on a FIFO basis. 

An indexed file is one in which each record has an identifier or key (surname, social security number, 
pure number, etc.). These records are stored sequentially with a key value; records with the same 
key value are linked together (index-linked). These records may be retrieved sequentially or a specific 
record may be retrieved by using its key value. 

If the actual mass storage address of a record is found by a prior retrieval, that record may be subse- 
quently stored or retrieved directly using the mass storage address. This is an efficient method 
for retrieving, updating, and restoring frequently used records. 
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GENERAL FILE FEATURES 



23E 



2.1 STORAGE AND RETRIEVAL 

The File Manager stores and retrieves information in three basic ways: 

o Sequential 

o Indexed 
o Direct 

In addition, variations for storage and retrieval are provided by combinations of the preceding and 
special options. The variations are: 

o Indexed-ordered 
o Indexed -linked 

To utilize mass storage efficiently, files are normally composed of a series of file record blocks (see 
Appendix B). A new file record block is assigned whenever a new record is added to the file, and 
the current lost record block of that file is too small to receive it. The series of record blocks is 
indexed by a file information segment (FIS), and all FISs are in turn indexed by the file directory, 
which acts as a master index to all files. To the user, it appears that each new record is filed 
sequentially in the designated file; however if direct access to files is made using the mass storage 
address, the user discovers that actual record blocks may be widely scattered over the logical unit 
holding the files. 



NOTE 

Because of the one-word mass storage 
sector address, large storage disk units 
(e.g., the storage module drive with the 
50-megabyte disk) have more than 32K 
sectors and must therefore be divided 
into several pseudo disks, each composed 
of 32K sectors and each with its own logi- 
cal unit number. Since the logical unit is 
one of the file parameters, it is possible 
that different files may be spread over a 
number of logical units (a single file is 
always on the same logical unit, however) . 
Storage and retrieval time are comparable 
on all pseudo disks. 
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2.1.1 SEQUENTIAL 

In sequential access, records are stored one at a time immediately following the last record stored 
| and are retrieved one at a time in the same order they were stored, starting from the beginning record 
of the file. 

Sequential access is best suited for retrieving all records on a FIFO basis. It is not suited to retriev- 
ing a particular record since all preceding records must first be retrieved. 

NOTE 

1. All files may be accessed sequentially. 

2. If a record is retrieved, the mass 
storage address of the record is 
returned to the user. The user then 
has the option of retrieving that 
record directly, using the mass storage 
address. 



2.1.2 INDEXED 

Indexed access is best suited for access of a specific record. Each record may be indexed by one and 
only one key. The key may be one or more words in length. Since all files are sequential, an indexed 
file may be termed indexed-sequential. Indexed access is only possible from an indexed file. 

A particular record can be stored and retrieved via a key. Each record key value can be translated 
into an index which can provide relatively quick access to the record. Indexed files require extra file 
space for the keys and key directories. 



2.1.3 DIRECT 

Direct access is best suited for frequently accessed records. A record must have been stored in a 
sequential or indexed file by a sequential or indexed store before it can be referenced directly. 

Direct procedures are normally used in updating records and in forming list structures. Since the 
File Manager provides record pointers for all records, all the files may be accessed directly. 
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2.1.4 VARIATIONS 



2.1.4.1 INDEXED-ORDERED 

When the indexed-ordered option is selected, indexed records can be retrieved in a manner similar to 
sequential retrieval. However, instead of a FIFO basis, records are retrieved starting at the record 
with the lowest numeric key value (or the key value specified in the first of the repeated index-ordered 
retrieve) and continuing through to the record with the highest numeric key value. When this type of 
access is used, a sort of the key values is done; therefore, the key value must be one word in length. 
It is recommended that key values for an indexed-ordered file include only non-negative values. 



2.1.4.2 INDEXED-LINKED 

In an indexed file, each record normally has a unique key value. However, if the indexed-linked option 
is selected, records with the same key value are linked together in either a LIFO or FIFO manner. The 
records are linked by allocating two words of each record for the linking record pointer. The retrieval 
of these records is an example of a list structure and is described in detail in Section 3. 3. LIFO or FIFO 
linking is specified by the user when a file is defined as indexed. 



2.1.4.3 LIST STRUCTURES 

Records may be retrieved as though they were part of a list structure by using the record pointers 
supplied by the File Manager and the direct method of retrieval. The user may form complex list 
structures by linking forward, backward, ring, sublist, etc. A record may be a member of an 
indefinite number of lists as long as two words for a record pointer are reserved in the record for 
each list. An example of a list structure is an indexed-linked file. 



2.2 FILE REQUEST 

Since the File Manager Executive (FILMGR) is core-resident and the individual request types are 
defined as File Manager entry points, the user program can make direct (utility type) calls to execute 
the needed operation. 

The four types of file requests are described in Section 3. They are: 

e Specification — Specification requests provide for: 
-Defining a file (DEFFIL) 
-Defining an indexed file (DEFIDX) 
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-Locking a file (LOKFIL) 
-Unlocking a file (UNLFIL) 
-Releasing a file (RELFIL) 
Sequential (STOSEQ, RTVSEQ) 
Indexed (STOIDX, RTVIDX, RTVIDO) 
Direct (STODIR, RTVDIR) 



These three file requests are used to 
store and retrieve records. 



The File Manager executes a request at the caller's priority level. If, however, the File Manager is 
executing a previous request, the request is queued by its priority level and is not executed until the 
currently active request and any higher level waiting requests have been executed. 

Associated with each request are a 12-word temporary buffer and one indicator word. The buffer holds 
information used to process the file request; upon completion of the request, the indicator word con- 
tains request execution status information. Each bit of the indicator word which is non-zero signifies 
an abnormal occurrence. If bit 15 is non-zero, the request has been rejected because of errors 
denoted in the other bits; if bit 15 is a zero but other bits are non-zero, the request has been com- 
pleted with an irregular occurrence (for example, an end of file has occurred). Note that bit 14 is 
a common bit for rejecting a request due to invalid parameters in a request. If the entire indicator 
word is zero, the request terminates normally. All error bits are shown in Figure 2-1. 



35 14 13 12 11 10 9 8 7 6 5 4 3 2 



1 



L_ 



FILE DEFINED/NOT DEFINED 
FILE LOCKED/NOT LOCKED 

LONG STORE OR SHORT READ 

END OF FILE (EOF) 

MORE RECORDS HAVE SOME KEY VALUES 

RECORD REMOVAL OR DOES NOT EXIST 
MASS STORAGE ERROR 

NO MORE FILE SPACE 

STORE DIRECT ADDRESS NOT IN FILMGR'S DISK SPACE 

WRONG FILE COMBINATION 

FILE DEFINED/NOT DEFINED AS INDEXED 
— INDEX-ORDERED FILE BUT KEY LENGTH 4 WORD 
UNPROTECTED REQUEST TO CHANGE A PROTECTED FILE 

REQUEST REJECTED DUE TO ILLEGAL PARAMETER LIST 

REQUEST REJECTED BECAUSE ONE OR MORE OF THE FOLLOWING: 



NOTES: 1. BIT 14, 13, 12, 11, 10, 8, 7, 5, OR IS SET. 

2. BIT 4 IS SET FOR STOIDX AND THE FILE IS NOT ORIGINALLY LFNKED 
IN THE DEFIDX REQUEST. 

3. BIT 2 IS SET FOR STOSEQ OR STOIDX (I.E., RECORD IN rccbuf IS 
LONGER THAN maxrl). 

4. BIT 1 IS SET FOR RELFIL, STODIR, LOKFIL (FILE LOCKED); OR UNFIL 
(FILE NOT LOCKED); OR RTVSEQ, RTVIDX, RTVIDO, RTVDIR ( ATTEMPT 
TO RETRIEVE FROM LOCKED FILE WITHOUT FILE COMBINATION). 



Figure 2-1. Status Word (REQIND) 
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2.3 RECORD FORMAT 

Each variable -length record is composed of three sections: header word, record pointers, and data 
words. 



HEADER WORD 

The first word of each record is reserved exclusively for the header word. The File Manager sets 
this word to the total length of the record when this record is stored. Once a record is defined, its 
length (and consequently the header word) cannot be changed. 



NOTE 

When storing and retrieving a record, the number of 
words in a record must include the header word. 



RECORD POINTERS 

A record pointer is a two-word mass-storage address which points to another record on mass storage. 
The first word is the sector location of the file record block in which this record resides. The 
second word contains the word the record starts in. If a file is indexed-linked, the second and third 
words are reserved for the record pointer, which points to the last record that was stored with the 
same key value. This is the same format as the recptr parameter passed back to the user from 
STOSEQ and STOIDX requests (see Section 3). The pointer words are used in all records, but are a 
part only of index- linked records. For all types of record storage and retrieval, the pointer is made 
available to the user. 



DATA WORDS 

Each record may have zero or more data words, which contain the actual record information. The 
information may be binary or ASCII. 



2.4 UPDATE PROTECTION 

Whenever a record is to be updated, the user must first retrieve the record and lock the file with a 
unique file combination. Subsequently, the updated record is stored and the file is unlocked with the 
same file combination, utilizing the store direct request (refer to Section 3). More than one record 
may be retrieved, updated, and restored as long as the same file combination that was used to lock 
the file is supplied. Note that the file should not be locked for an extended period of time because 
other users, who may also wish to update records, cannot access the file until it is unlocked. Thus a 
retrieval, which attempts to lock an already locked file with a different combination is queued; it cannot 
be executed until the file is unlocked. 
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If a number of files are to be locked, it is advisable to lock and unlock the files in a given sequence. 
For example, lock files in ascending numerical order and unlock them in descending numerical order. 

| A retrieval without a file combination or storing a new record is permitted on a locked file with the 
understanding that one or more records of that file are in the process of being updated. Note that an 
update into an unlocked file or a locked file using an incorrect file combination results in a file request 
error. 

The file combination must necessarily be unique so that no two requests use the same file combination. 
This can be accomplished by using the ASSIGN statement in FORTRAN or the RTJ instruction in 
Assembly language. 



2.5 UNPROTECTED FILE REQUESTS 

Unprotected programs are assumed not to be error-free; therefore, certain restrictions have been 
placed on unprotected file requests. 

An unprotected file request cannot update a record in a file because it cannot use the store direct 
request. This restriction is imposed because the File Manager has no way to check the validity of the 
record pointer in the store direct request. The restriction is mitigated by the assumption that 
background programs primarily retrieve records (for example, data reduction, analysis, etc.) and 
that records can always be retrieved, updated, and stored as new records in another unprotected file. 

Since updates cannot be done, file locking is illegal for unprotected file requests. Note that unprotected 
file requests may not store records into or remove records from files that were defined by protected 
programs. 



NOTE 

If there is not enough allocatable core for both the 
File Manager and Job Processor modules, file 
requests from background can hang batch processing 
indefinitely. 



2.6 REQUIREMENTS AND LIMITATIONS 

The File Manager requires certain information to establish the file structure and imposes limitations 
on those files. 



2.6.1 MAXIMUM RECORD LENGTH 

The effective maximum record length and file record block length are determined as a function of the 
maximum record length specified by the define file request for each file. It places a maximum limit 
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on the length of records for that file, and also establishes a block of sector(s) that will be allocated 
when the first record is stored into the file. Subsequent records are stored into this block until it is 
full, then another equal block of sector(s) is automatically allocated. This process is continued as long 
as there is mass memory space available. Thus a file record block may contain one or more records 
(see Appendix B). 

File record blocks require a three-word header. For this reason, the effective maximum record 
length is equal to the specified maximum record length if the specified maximum record length plus 3 is 
equal to an integral multiple of 96. Otherwise, ihe effective maximum record length is equal to the 
least integer value n such that 

1) n is greater than the specified maximum record length, and 

2) N = 96* m - 3 for some positive integer m. 

Thus, specified maximum record length values of 3, 93, and 94 would result in effective maximum 
record lengths of 93, 93, and 189 respectively. 



2.6.2 EXPECTED NUMBER OF RECORDS WITH DIFFERENT KEY VALUES 

The expected number of records with different key values is specified by the define file indexed 
i(DEFIDX) request parameter numekv (refer to Section 3) for each indexed file. Note that if a file 
is not indexed-linked, this is equivalent to the number of records in the file after the file is fully 
established by adding records. The expected number of records with different key values establishes 
the structure of the indexed directories. A relatively accurate estimate is important if the number of 
expected key values exceeds 8, 464. 

Too low an estimate may result in more mass storage accesses per indexed request, while too high an 
estimate may result in excessive core allocation for the indexed directories per indexed request. 



2.6.3 PARAMETER LIMITATIONS 

The following limitations are necessary: 

File number range 1 through 32, 767 

Record length range 1 through 32,767 

Number of expected records 

(with different key values) range 1 through 32, 767 

Key value length range 1 to 63 words 

File combination range 1 through 16, 383 

Key value range for indexed - 

ordered files through 32, 767 
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CAUTION 

Users are warned that programs making File Manager 
requests which contain relative parameters will not 
execute properly in partitioned core or at addresses 
above ENDOV4, the top of partition (normally 8000 ). 



2.6.4 RESTRICTIONS WHEN USING MORE THAN ONE LOGICAL UNIT FOR FILE SPACE 

The File Manager initializes the file space pool for every File Manager logical unit at the same time. 
This initialization occurs when the first define file request is encountered after an operating system 
is built. The initialization of a file space pool for a given logical unit involves writing the file space 
pool thread on that unit in the first sector which is available for File Manager use. 



CAUTION 

1. At the time the first define file request is executed, 
all logical units which are to be used (now or later) 
for file storage must be operating. 

2. The disk pack mounted on a drive at the time the first 
define file request is executed must be mounted on 
that drive when the File Manager uses that unit for 
storage. 



2.7 SPACE ALLOCATION 



2.7.1 FILE SPACE ALLOCATION 

File space is allocated by the define file request for file records or by the define file indexed request 
for file indexed directories. Provision is made to return file space by the release file request and the 
retrieve/remove requests. Returned file space is not released for other users; it remains under the I 
control of the File Manager. Note that: 

• Every record in a file must be on the same logical unit. 

• Every indexed directory for a file must be on the same logical unit. 

• Logical units for files must be mass memory devices. 

The first time a define file request is encountered after a 1700 operating system with the File Manager 
is built, a file space list and a file space pool are constructed for each logical unit that has available 
file space. The File Manager tests the value of the SYSDAT FILMGR core location FIDSEC. The value 
of FIDSEC is zero until after the first define file request is encountered. 
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A file space list is composed of one or more blocks of available space. Each block is a threaded 
sequence of segments of mass memory such that each segment has the same length in sectors as every 
other segment in the block. 

For example, there may be a block of all available two-sector segments. At the time the system is 
built, the user determines what blocks (i.e. , what available segment lengths) are to be included in the 
file space list. All available file space which lies in a segment of a length other than those included in 
the file space list is included in a file space pool. The advantage of keeping as much of the available 
file space as possible in the file space list is that available space there can be allocated much more 
quickly than can space in the file space pool. The disadvantage of having too many blocks in a file 
space list is that two words of core (in SYSDAT) are used for each block. 

Consider the following example. The user determines that the file space list is to be composed of 

• A block of segments one sector long, 

• A block of segments two sectors long, and 

• A block of segments four sectors long. 

Suppose at a given time there are file space segments of various lengths: one sector, two sectors, 
three sectors, four sectors, six sectors, eight sectors, 20 sectors, and 10,000 sectors. The file 
space list and the file space pool are represented in Figure 2-2. I 

The efficiency of the File Manager can be optimized by determining, at the time the system is built, 
what file space lengths will be used. If only a small number of different lengths are needed, a block 
for each of these lengths can be included in the file space list. For example, suppose only segments 
of one sector, two sectors, and four sectors are to be allocated for file space. A block for each of 
these lengths in the file space list requires only six words of core storage in SYSDAT. 

Refer to Appendix B for details concerning file space requirements. Note that space must be 1 

allocated for key directories and key information segment blocks as well as for file records when using 
indexed files. 



2.7.2 FILE SPACE AUDIT 

When there is insufficient file space to define a new file or to store another record in a given file, the 
File Manager will indicate this condition to the requestor. In many cases, it is desirable to know when 
file space is running low before all the file space is gone. Files which are no longer in use could then 
be released to make additional space. A user early-warning program may be written to monitor the 
ratio of available space and total space for each logical unit. These parameters are located in the 
FILMGR SYSDAT parameter area. For example, for File Manager logical unit 1 we may find in 
SYSDAT: 



LUE1 


NUM 
NUM 






NUM 


X 




NUM 


y 
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CORE (SYSDAT) 



MASS STORAGE 



POOL 
BLOCK OF 
THREE- 
SECTOR 

SEGMENTS 



POOL 
BLOCK OF 
SIX-SECTOR 
SEGMENTS 



POOL 
BLOCK OF 
EIGHT- 
SECTOR 
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POOL 
BLOCK OF 
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AVAILABLE 
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Figure 2-2. Example of File Space Pool and File Space Test 
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Thus, one could calculate for logical unit one: 

(LUE1 + 2) = x 
1 (LUE1 + 3) y 

giving the ratio of file space available to original file space for this logical unit. Location LUE1 is the 
same location as that of FSLIST in Figure 2-2. I 



2.7.3 CORE ALLOCATION 

The individual file request processors (e.g. , store sequential), the information segment for a file 
(FIS — see Appendix B), and its indexed directory (KIS — see Appendix B) are placed in allocated 
core. Each item will remain in core to conserve mass memory accesses, as long as it enjoys 
sufficient usage by the File Manager user(s). Once a certain item has not been utilized for a period 
of time, its core will be released and the next use of it will require a mass memory transfer. 

The time period for each of the above is a system parameter determined when the operating 
system is built. 



2.8 FILE VALIDITY CHECK 

To minimize mass memory I/O traffic, the File Manager allows file information to remain in 
allocatable core until a time-out occurs, at which time the information is updated on mass storage. 



CAUTION 

Abnormal system stops and autoloads can destroy 
this information and will eventually cause fatal file 
errors. 



If the system contains a File Manager, a file validity check is performed each time the system is 
autoloaded. The check is preceded by the message: 

CHECKING FILES - 

on the system comment device, and consists of a trace of all file space threads on mass storage. If 
the threads are found to be valid an OK is printed. If any errors are found the user is given the option 
of continuing with the autoload or purging all system files (i. e. , reverting all File Manager tables to 
a condition prior to the loading of any files). If this option is selected the files would have to be 
reloaded from a user-written backup dump. 
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CAUTION 

When the File Manager is installed with more than one 
mass memory unit, all mass memory units must be 
operating when the File Manager is used for the first 
time after initialization of the system. The File Man- 
ager writes file threads on each unit at this time. 
Thereafter, the same disk pack must remain on each 
mass memory unit as when the File Manager was first 
used or file errors will occur, even if files are not 
defined on those units. 
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FILE REQUEST DESCRIPTIONS AND CALLS 



All file request calls to the File Manager may be written as FORTRAN type calls or as Assembly 
language macros as in the following descriptions. The Assembly language call format, without the 
use of macros is described at the end of Section 3. 

In each of the following sections, three examples of each type of call are given: the FORTRAN call 
(including the parameter list) and two assembly language calls (the first in absolute format and the 
second in relative format). In both cases, only the first word of the parameter list is given, since 
the coding of the user program may select the form of assembly language (usually macro) call. In the 
latter case the first parameter is normally the address of the parameter list. In all cases, the user 
program must set up all the parameters listed in the FORTRAN call. 

Error considerations are returned to the user by means of the request status word (required parameter), 
In most cables where the status does not equal 0, bit 15 is set (see figure 2-1) indicating that the 
request was rejected. If rejection was generated by a bad parameter in the request, bit 14 is also 
set. In other cases the individual error bits are set together with bit 15. 

A summary of all File Manager request calls is given in table 3-1. 

CAUTION 

Programs making File Manager requests which 
contain relative parameters will not execute 
properly in partitioned core or at addresses 
above ENDOV4. 



3.1 SPECIFICATION REQUESTS 

Specification descriptions define a file, determine if it can be used at this time, and release files. 
The calls are discussed in the following order: 

Define file (DEFFIL) 
Define file indexed (DEFIDX) 
Lock file (LOKFIL) 
Unlock file (UNLFIL) 
Release file (RELFIL) 
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TABLE 3-1. SUMMARY OF FILE MANAGER REQUEST CALLS 



File Initialization, Restriction, and Status 



Type 
Instruction 



Instructiont 



Parameters Supplied by User tt 



Define a 
normal file 



DEFFIL 



Define an 

indexed 

file 
F 



DEFIDX 



Lock a file 



LOKFIL 



Unlock a 
file 



Release a 
file 



UNLFIL 



RELFIL 



filnum 

maxrl 
lu 

reqbuf 

reqind 

filnum, lu, 
reqbuf, and 
reqind 

numekv 



keylth 



Arbitrary. File number (<7FFF) is assigned 
by user 

Maximum length of record in the file 

Logical unit (identification of disk or pseudo disk) 
where file is stored 

12-word buffer (normally assigned within the user 
program; however, may be anywhere so long as 
protect value is same as user program) 

Free status word following request 
Same as in DEFFIL above 



Number of different key values for all records to be 
filed in the indexed file (a single alphanumeric key 
value identifies the record. This must be a pure 
numeric if the user desires the index-ordered 
capability. ) 

Number of alphanumeric 16-bit words in key (^ 63). 
Also flags to show index-ordered or index-linked. 



filnum, reqbuf, Same as in DEFFIL above 
and reqind 

filcom File combination (an arbitrary number < 7FFF) 

This instruction is executed only by protected programs. 



filnum, filcom, 
reqbuf, and 
reqind 



Same as in LOKFIL above. 



This instruction is executed only by protected programs. 

filnum, regbuf, Same as in DEFFIL above 
and reqind 

This instruction releases space for use by other file only. 



^Each of these instructions can be written in FORTRAN (e.g. , CALL DEFFIL), or as an assembly 
language macro (e.g. , DEFFIL from an absolute program, DEFFIL* for a relative program). 

' ' Parameter lists may be defined to be constants (e.g. , a set of labels with the labels equated to 
constant values) or as addresses where the parameter values may be found (e.g. , indirect 
relative, or absolute addresses where the parameter values are stored). 
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TABLE 3-1. SUMMARY OF FILE MANAGER REQUEST CALLS (Continued) 



Record Instructions 


Type 
Instruction 


Instruction t 


Parameters Supplied by User ft 


Store a 
sequential 


STOSEQ 


filnum, reqbuf, 
reqind 


Same as in DEFFIL on the previous page 


record 




recptr 


Two-word label where File Manager stores mass 
storage address of pointer to record 






recbuf 


Buffer where record is currently stored in main 
memory (in user program) 






reclth 


Length of recbuf 


Retrieve a 
sequential 
record 


RTVSEQ 


filnum, recptr, 
reclth, reqbuf, 
reqind 


Same as in STOSEQ above 






filcom 


Same as in LOKFIL on the previous page 






recbuf 


User-supplied buffer where retrieved record is to be 
written in main memory (in user program) 


Store an 
indexed 


STOIDX 


filnum, reqbuf, 
reqind 


Same as in DEFFIL on the previous page 


record 




recptr, reqbuf, 
and reclth 


Same as in STOSEQ above 






keyval 


Key for this record. Must be equal to keylth 
(including blanks) 


Retrieve an 

indexed 

record 


RTVIDX 


filnum, keyval, 
recptr, reclth, 
reqbuf, 
and reqind 


Same as in STOIDX above 






filcom 


Same as in LOKFIL above 






recbuf 


User-supplied buffer where retrieved record is to be 
written in main memory (in user program) 


t Each of these instruction 
language macro (e. g. , D 


s can be written in FORTRAN (e.g., CALL DEFFIL), or as an assembly 
EFFIL from an absolute program, DEFFIL* for a relative program). 


tf Parameter 
constant va 
relative, 01 


lists may be 
nes) or as ac 
' absolute adc 


defined to be constants (e.g., a set of labels with the labels equated to 
dresses where the parameter values may be found (e.g. , indirect 
resses where the parameter values are stored). 
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TABLE 3-1. SUMMARY OF FILE MANAGER REQUEST CALLS (Continued) 



\'U 



Record Instructions 


Type 






Instruction 


Instruction? 


Parameters Supplied by User tt 


Retrieve an 


RTVIDO 


Same parameters as RTVIDX above 


index- 
ordered 




keyval Must be purely numeric to use this retrieval mode 


record 






Store an 


STODIR 


filnum, recptr, Same as in STOSEQ above, but recptr is known and 


updated 




recbuf, and its value must be supplied 


record 




reqind 


Retrieve a 


RTVDIR 


Same parameters as in RTVSEQ above, but recptr is known and its 


file 




value must be supplied 


directly 






+ 

1 Each of these instructions can be written in FORTRAN (e. g. , CALL DEFFIL), or as an assembly 


language macro (e. g. , DEFFIL from an absolute program, DEFFIL* for a relative program). 


tt 

1 'Parameter 


lists may be defined to be constants (e. g. , a set of labels with the labels equated to 


constant va 


ilues) or as addresses where the parameter values may be found (e.g., indirect 


relative, or absolute addresses where the parameter values are stored). 



3.1.1 DEFINE FILE (DEFFIL) 

A file must be defined before any information can be stored or retrieved. A file cannot be defined if it 
is already defined. However, the file could be redefined if it had been previously released (refer to 
release file in this section). 

The define file request specifies: 

• The file number of the file being defined (permitting other requests to reference this file) 

• A value to determine the length in words of each block of file space which is allocated to a 
file when needed. This value also places an upper limit on the length of any record in a 
file. Any attempt to exceed this limit results in an error. 

• A logical unit where the file's records will be stored 
o A temporary buffer for processing the request 

© An indicator word, denoting the request's status upon completion (figure 2-1) 
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The FORTRAN format for the define file call is: 



CALL DEFFIL (filnum, maxrl,lu,reqbuf, reqind) 



Where: 



filnum 
maxrl 

hi 



is the file number; it contains a positive integer specifying the file to be defined. 



is 



is 



reqbuf is 



reqind is 



the maximum record length; to be used for determining the effective maximum 
record length and file record block length. It is a positive integer. 

the logical unit; it contains a positive integer specifying where the file's 
records are to be stored. 

the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

the file request status word; at the end of request processing the File Manager 
sets the indicator bits as appropriate. If no bits are set, the request was 
completed without error. The request processor checks for errors, and in 
most cases rejects the request. The status word is available to the user for 
discovering the cause of request rejection. 



NOTE 

Limits for various parameter values 
are set forth in section 2. 



The Assembly language macro format is: 

DEFFIL filnum . . . Produces a call with an absolute address for the parameter list. 

DEFFIL* filnum . . . Produces a call with a relative address for the parameter list, 

as for a run-anywhere program) 

Note that to use the macro call, an FLDF macro call must be included in the program, as described 
at the end of this section. 

Error considerations (reqind) are as follows: 

e DEFFIL sets bits 14 and 15 (rejecting the request) if: 
-maxrl > 2 - 1 
-lu< 
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-lu is not a mass memory device 

-filnum < 

DEFFIL sets bit 15 (rejecting the request) if: 

-filnum has already been defined (bit is also set) 

-A mass memory error occurs (bit 7 is also set) 

-No more file space is available (bit 8 is also set) 



3.1.2 DEFINE FILE INDEXED (DEFIDX) 

This request continues the defining process by specifying that a file which has already been defined by 
a DEFFIL call. A file must be defined indexed before any information can be stored or retrieved 
using an indexed key. Since a file cannot be defined as indexed if records have already been sequentially 
stored into it, this request should be made immediately after the file is initially defined. 

A file cannot be defined indexed if it is not defined, if it is already defined indexed, or if records have 
already been stored sequentially into it. An unprotected program cannot define indexed a file which was 
defined by a protected program. 

If the records of a file are to be ordered by key value, the key length of the record must be one word. 

The FORTRAN format for the define file indexed call is: 



CALL DEFIDX (filnum, numekv , keylth , lu , reqbuf , reqind) 

Where: filnum is the file number; it contains a positive integer specifying the file to be defined 

as indexed. 

numekv is the number of expected key values; it contains a positive integer estimating 
the number of records with different key values to be stored in the file. 

keylth is the key length word, with the indexed options: 



Bits through 5 
6 through 12 
13 

14 
15 



Length of the key in words (<63) 

Reserved 

1 First-in/first-out (FIFO) linking (bit 15 must be 
set). If this bit is not set and bit 15 is set, last- 
in/first-out (LIFO) linking is implied. 

1 Indexed-ordered file 

1 Indexed-linked file 
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lu is the logical unit; it contains a positive integer specifying the disk that stores 

the file's indexed directories and records. 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process a request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

^/The Assembly language macro format is as follows: 

DEFIDX filnum . . . Produces a call with an absolute address for the parameter list 

DEFIDX* filnum . . . Produces a call with a relative address for the parameter list, 

as for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program, as described 
at the end of this section. 

Error considerations (reqind) are as follows: 

• DEFIDX sets bits 14 and 15 (rejecting the request) if: 
-filnum < 0. 

-numekv< 0. 

-lu is not a mass memory device. 

-lu is illegal. 

-FIFO is selected but indexed-linking is not selected. 

• DEFIDX sits bit 15 (rejecting the request) if: 

-filnum is released or not defined (bit is also set). 

-A mass memory error occurs (bit 7 is also set). 

-No more file space is available (bit 8 is also set). 

-The file has records stored sequentially before the file is defined as indexed or the file 
is already indexed (bit 11 is also set). 

-keylth does not equal one word for an indexed-ordered file (bit 12 is also set). 

-The file is protected (bit 13 is also set). 



3.1.3 LOCK FILE FOR PROTECTED PROGRAMS ONLY (LOKFIL) 

A file may be locked by protected programs when it is possible that more than one program may be 
attempting to update the same file. 
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A file cannot be locked if it is not defined, if it is already locked, or if the lock file request is issued 
on a protected file by an unprotected program. An alternate method of locking a file is provided in the 
retrieve requests (the alternate method is the usual way of locking files during updating of records). 

The lock file request specifies: 

• The file number of the file being locked 

• The file combination required to store in this file 

• A temporary buffer for processing this request 

• An indicator word, denoting request's status upon completion (Figure 2-1). 

The FORTRAN format for lock file call is as follows: 
CALL LOKFIL (filnum, filcom,reqbuf, reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file being locked. 

filcom is the file combination with the remove option; bits through 14 contain a 

non-zero number which must be used in subsequent store or remove requests, 
as well as in the unlocking request; bit 15 is not used. 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is as follows: 

LOKFIL filnum . . . Produces a call with an absolute address for the parameter list 

LOKFIL* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program as described 
at the end of this section. 

Error considerations (reqind) are as follows: 

• LOKFIL sets bits 14 and 15 (rejecting the request) if filnum < 0. 

• LOKFIL sets bit 15 (rejecting the request) if: 
-filnum is not defined or is released (bit is also set). 

-The file is locked with a different combination (bit 1 is also set). 
-An unprotected program is making the request (bit 13 is also set). 
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3.1.4 UNLOCK FILE FOR PROTECTED PROGRAMS ONLY (UNLFIL) 

A file may be unlocked when there are no further updates to be done. The same file combination that 
was used to lock the file must be used to unlock it. An alternate, method of unlocking a file is provided 
in the store direct request. 

A file cannot be unlocked if it is not defined or not locked, if the combination is incorrect, or if an 
unprotected program attempts to unlock a file defined by a protected program. 

The unlock file request specifies: 

• The file number of the file being unlocked 

• The file combination used to previously lock the file 

• A temporary buffer for processing the request 

• An indicator word, denoting the request's status upon completion (Figure 2-1). 

The FORTRAN format for unlock file call is as follows: 

CALL UNLFIL (filnum,filcom, reqbuf, reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file being 

unlocked. 

filcom is the file combination; bits through 14 contain a non-zero number which is 
identical to the combination that was used to lock the file; bit 15 is not used. 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is as follows: 

UNLFIL filnum . . . Produces a call with an absolute address for the parameter list 

UNLFIL* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program as described 
at the end of this section. 
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Error considerations (reqind) are as follows: 

• UNLFIL sets bits 14 and 15 (rejecting the request) if filmim ^ +0. 

• UNLFIL sets bit 15 (rejecting the request) if: 
-filnum is not defined or released (bit is also set). 
-The file is not locked (bit 1 is also set) . 

-The file is locked with another combination (bit 10 is also set). 
-An unprotected request tried to unlock the file (bit 13 is also set). 

3.1.5 RELEASE FILE (RELFIL) 

A file may be released when there is no further use for it. All the space reserved for the file's data 
records, as well as all information associated with the file's indexing, is returned to the File Manager 
for future utilization by other files. The space is not returned to the disk manager for general use. 

A file cannot be released if it is not defined or if it is locked. An unprotected program cannot release a 
file defined by a protected program. 

The release file request specifies: 

• The file number of the file being released 

• A temporary buffer for processing the request 

I • An indicator word, denoting the request's status upon completion (figure 2-1) 

The FORTRAN format for release file call is as follows: 
CALL RELFIL (filnum, reqbuf, reqind) 

Where: filnum is the file number; it contains a positive integer specifying the file to be 

released. 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

I reqind is the file request status word. At the end of request processing, the File 

Manager sets the indicator bits as appropriate. 

The Assembly language macro format is as follows: 

RELFIL filnum Produces a call with an absolute address for the parameter 

RELFIL* filnum Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 
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Note liiat to use the macro call, an FLDF macro call must be included in the program as described 
later in mis section. 

Error considerations (reqind) are as follows: 

• RELFIL sets bits 14 and 15 (rejecting the request) if filnum < 0. 

• RELFIL sets bit 15 (rejecting the request) if: 
-filnum is released or not defined (bit is also set). 
-The file is locked (bit 1 is also set). 

-A mass storage error occurs (bit 7 is also set). 

-An unprotected request attempts to release the protected file (bit 13 is also set) . 

If a mass memory occurs while trying to release the FRBs and FIS threads, the message 

F.M. ERROR 

is delivered to the comment device. 

3.1.6 EXAMPLES OF SPECIFICATIONS REQUESTS 

As a part of a computer system to aid a law enforcement agency, a first offense file is defined. The 
record format is to be as follows: 



Word 


Contents 


1 


Header 


2-25 


Name 


26-28 


Date of first arrest 


29-30 


Time of first arrest 


31 


Violation code 
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Note that a record length of 31, a factor of 93, is used. By setting the maximum record length to 93, 
the maximum record length and the effective maximum record length are equal. Thus, no space is 
wasted in the mass memory storage of the file records. 

Periodically, the contents of the first offense file are to be written on magnetic tape. The FORTRAN 
code shown in Example 1 is used to define the file initially as well as to re-initialize the file after each 
transfer of its contents to tape. 

Note that a release file request occurs before the file is defined. Therefore, when the file is defined it 
will contain none of the previously stored records. 

The file records are to be accessed by license number, expressed as four ASCII words. Note that the 
license number is not part of the data in the record, but that its length in words is specified as the key 
length when the file is defined as indexed. An estimate of 1, 000 first offenses will be recorded in the 
file before the file is cleared and re-defined. Thus, numekv = 1000. 



EXAMPLE 1: 



Program 

INTEGER RE(3BUF-U2>-,REQIND 
DIMENSION IOBUF-CSfl} 



Comments 



Reserves space for file buffer, 
status word, and I/O buffer 
(for error message) 



C RELEASE THE FIRST OFFENSE FILE 
I IFLNUM=20 

CALL RELFIL-CIFLNUri-,RE(3BUF-,RE(2IND} 

C CHECK FOR ERRORS 
I IF -CREfllND-LT.D} GO TO 1D0D 

C DEFINE THE FIRST OFFENSE FILE 

| MAXRL=T3 

C LOAD A-REGISTER UITH FILES LOGICAL UNIT-, IFLUn AN EXTERNAL. 

■ C SAVE IN LOCAL VARIABLEn LU. 
C LDA =XIFLU 
C STA LU 

ASSEM $CDDDn + IFLU-,$bAOD-.LU 



Specifies file number 



Checks status of file after 
last use 



Defines record length (optimum) 



Executes in assembly language 
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Program 



Comments 



CALL DEFFIL -CIFLNUMnM AXRL -.LU nREflBUF -.REC2IND} 
C CHECK FOR ERRORS 

IF -CREQIND.LT. D> GO TO 1QDD 
C DEFINE FILE TO BE INDEXED BY LICENSE NUMBER 

KEYLTH=4 

NUMEKV=1BQD 

CALL DEFIDX •CIFLNUn-.NUnEKV-.KEYLTH-.LU-.REflBUF-.REfllND} 



IF -CREfllND-LT-Q} GO TO 1DDD 



Defines file (sequential) | 

Is file defined as requested ? 1 



Changes to indexed file before 
entering any records 

Is file indexed as requested? 



10DD CALL SETBFR-CIOBUF-,Sa> 



WRITE -CM-.3000J IFLNUM-, REflIND 
C FOLLOW ERROR EXIT PATH 



Error message preparation 
(display status word in hexa- 
decimal format) 



3D00 FORMAT -CSHFILE iISiflH ERROR $-,$M} 



Format for error message 



The FORTRAN code shown in Example 2 illustrates the proper method for determining a file combination 
so that uniqueness is guaranteed. The figure also shows acceptable call statements to lock and unlock a 
file. This code must be part of a protected program according to File Manager restrictions. 



EXAMPLE 2: 



Program 



INTEGER REflBUF-C12}-,RE<2IND-,FILCOM 
DIMENSION IOBUF-CSB}. 



Comments 



See comments in example 1. 



IFLNUM=IBASE+303 
C N0TE**0NLY THIS METHOD SHOULD BE USED TO GENERATE FILE 
C COMBINATIONS** 
5DDD ASSIGN 2D0D TO FILCOM 
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Program 

CALL L0KFIL-CIFLNUn-,FILC0n-,REflBUF 1 RE(3IND> 
IF -CREdlND.LT.O} 60 TO 1DDD 



Comments 



C UPDATE FILE 



CALL UNLFIL-CIFLNUM-.FILCOn-.REQBUF-.REfllND} 
IF -CREflIND.LT.D3- GO TO 1DDD 



1DDD CALL SETBFR-CIOBUF-.SA} 

URITE -CM-.3DDD1 IFLNUM-,REC2IND 
C FOLLOU ERROR EXIT PATH 



3QDD FORMAT -CSHFILE-.IS-.fiH ERROR $-,$M} 



The FORTRAN code for a part of the files initialization procedure for a given system is shown in 
Example 3. The Example 3 program uses the information already in the file; releases it, checks 
for file usage error, and redefines the file only if no error exists. The first define file request is 
used as a test to see if the file has been previously defined. If so, the information in the file will 
be used before the file is released and redefined. Ti not, initial condition records are stored in the 
file. 



EXAMPLE 3: 



Program 



Comments 



DlrtENSION IRE<JBF-C15>,I0BUF-CSfi> 



See comments in example 1. 



IFLNUM=S 
MAXRL = T,3 
LU = fi 

CALL DEFFIL-CIFLNUM-,MXRL-,LU-,IRE<2BF-,IRE<2ID} 
C UAS FILE PREVIOUSLY UNDEFINED 

IF -CAND-CIREt3ID-,l}.E(2.D} GO TO 10DD 



Checks bit of status word 
(file undefined) 



3-14 



39520600 D 



Program 



Comments 



C FILE UAS PREVIOUSLY DEFINED 
C CHECK FOR FILE ERRORS 

IF ■CAND-CIREfllD-.SDmaj-.NE.Q} GO TO 5DDD 



Checks bits 10, 4, and 3 of status 
word (wrong combination, non- 
unique key, end-of-file) 



I 



C NO FILE ERRORS, PROCEED TO USE 
C INFORMATION IN FILE 



C OLD FILE INFORMATION HAS BEEN USED. 
C RELEASE AND RE-DEFINE FILE 5 

CALL RELFIL-CIFLNUMiIREUBFiIREfllD} 

IF -CIREfllD.LT.Q} GO TO SDOD 

CALL DEFFIL {IFLNUM-iMAXRL-,LU-.IRE<2BF-,IRE<2ID} 

IF -CIREaiD.LT.D} GO TO SDDO 
C STORE INITIAL CONDITIONS RECORDS INTO FILE 



Operator specifies initial con- 
ditions for each record and 
stores them with STOSEQ 
requests 



1QDD 



C PRINT ERROR MESSAGE 
SOOD CALL SETBFR-CI0BUF-.5A} 

WRITE -CMibDOO} IFLNUM-.IREC2ID 
bDOD FORMAT -CbH FILE-, IS-.5H ERROR $-,$4} 



3.2 SEQUENTIAL REQUESTS 



3.2.1 STORE SEQUENTIAL RECORD (STOSEQ) 

Records may be stored sequentially in a file once it is defined. A sequential record is always stored 
as the last record of the file; its record pointer is returned to the caller so that the record may be 
accessed directly. A sequential store is permitted in a locked file; the status word indicates that the 
file was locked. 

The length of the record cannot exceed the specified maximum record length (maxrl). A 
record cannot be stored sequentially if the file is indexed or if it is not defined. An unprotected 
program cannot store a record in a file which is defined by a protected program. 
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The store sequential record request specifies: 

The file number of the file where the record is being stored 

A buffer for returning the record pointer 

A buffer of information to be stored as the record 

A temporary buffer for processing the request 

An indicator word, denoting the request's status upon completion (Figure 2-1). 

The format for store sequential record call is: 

CALL STOSEQ (filnum, recptr, recbuf , reclth, reqbuf , reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file into which a 

record is being stored. 

recptr is the record pointer set by the File Manager. It is a two-word array which 
contains the mass storage address of the record just stored. 

/ recbuf is the record buffer; it is an array of reclth words containing the record to be 
stored. 

reclth is the record length; it contains a positive integer specifying the length of the 
record. 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is: 

STOSEQ filnum . . . Produces a call with an absolute address for the parameter list 

STOSEQ* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program) 

If the reclth parameter is blank, the current record length is left unchanged. Note that to use the macro 
call, an FLDF macro call must be included in the program, as described later in this section. 

CAUTION 

The File Manager assumes that the three words 
preceding the record buffer are part of the user's 
program. To optimize storing time, the contents 
of these three words are temporarily altered to 
contain the FRB header words whenever the File 
Manager writes the first record in an FRB to mass 
memory (Appendix B). After the transfer occurs, 
the File Manager restores the original contents of 
the three words. 
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CAUTION 

The user's program may be in a multiprogramming 
environment. In this case, if the record buffer is 
at the beginning of the program and the three words 
preceding the record buffer extend beyond the user's 
program, the three words could overlap another 
program or core storage, such as a core allocation 
thread which might be used before the original 
contents are restored. 



Error considerations (reqind) are as follows: 

• STOSEQ sets bits 14 and 15 (rejecting the request) if: 
-filnum < 

-recptr does not point to an address in FILMGR's space 
-Record length £ 

• STOSEQ sets bit 15 (rejecting tine request) if: 

-The file is not defined or released (bit is also set) 

-The record exceeds maxrl (bit 2 is also set) 

-A mass storage error occurs (bit 7 is also set) 

-There is no more file record space to store records (bit 8 is also set) 

-The file is defined as indexed (bit 11 is also set). 

-An unprotected program attempts to store a record in a protected file (bit 13 is also set). 

3.2.2 RETRIEVE SEQUENTIAL RECORD (RTVSEQ) 

Record(s) may be retrieved sequentially from a file once the file is defined and at least one record has 
been stored into the file. (The file may have been defined by either a protected or an unprotected 
program.) Each record in the file may be retrieved sequentially be repeatedly executing one RTVSEQ 
call until an end-of-file indication is given. If there are n records in a file, the first RTVSEQ call will 
retrieve the first record that was stored into the file, the nth RTVSEQ call will retrieve the last record 
that was stored into the file, and the n + 1st RTVSEQ call will produce an end-of-file indication. For 
each of the n calls, one record is retrieved along with its corresponding record pointer, so that the 
record may be accessed directly. If there are no records in the file, the first call will produce an 
end-of-file indication. 
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General information for retrieve sequential records is as follows: 

• It is not necessary to retrieve all the records from the file. 

• The first and subsequent records can be re-retrieved by a new call or by re -initializing the 
current call record pointer. 

A file should be locked with a file combination when a record is retrieved for updating. Such records 
may be retrieved from a previously locked file if the same file combination that was used to lock the 
file is specified. These retrieved and updated record(s) may be restored into the locked file via the 
store direct record call using the same file combination. Note that sequential retrievals without a file 
combination are permitted from a locked file; however, the status word indicates that the file was 
locked. A record may be removed from a non-indexed file as it is retrieved. The first part of a 
record of any desired length may be retrieved; however, the status word indicates that a short record 
was retrieved. 



A record may be retrieved, but cannot be removed from an indexed file using a retrieve sequential 
request. A record is not retrieved sequentially if the record was previously removed from the file; 
however, subsequent records which exist may be retrieved by repeating the same call. A record 
cannot be retrieved if the file is not defined. An unprotected program may retrieve, but cannot 
remove, a record from a file which was defined by a protected program. 

The retrieve sequential record request specifies: 

The file number of the file from which the record is being retrieved 

The file combination, if the file is to be locked, or the record that is to be retrieved from 
a locked file 

Whether the record is to be removed from the file 

A buffer for returning the record pointer 

A buffer for receiving the record to be retrieved 

A temporary buffer for processing the request 

An indicator word, denoting the request's status upon completion (Figure 2-1). 



CAUTION 

If a ETVSEQ call is repeatedly executed as a part of a 
loop, the File Manager uses the information left in the 
request buffer and the record pointer at the end of one 
call as information for the next call in the loop. Hence, 
these parameters must not be changed between calls in 
the loop. The contents of the record buffer may be 
changed between calls as the user desires. The record 
length may be changed if the user wishes to vary the 
number of words retrieved. 
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The format for retrieve sequential record call is as follows: 

CALL RTVSEQ (filnum,filcom,recptr,recbuf, reclth,reqbuf,reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file from which 

the record is to be retrieved. 

filcom is the file combination with the remove option; bits through 14 contain a 

non-zero number (if the file is or is to be locked) , specifying the combination 
(which is or is to be) used to lock the file; bit 15 set to a one indicates that 
the record is to be removed from the file. 

recptr is the record pointer set by the File Manager. It is a two-word array that con- 
tains the mass storage address of the record just retrieved. Initially, both 
words must be set to zero by the requester. 

recbuf is the record buffer; it is a non-preset array of reclth words, where the File 
Manager transfers the retrieved record. 

reclth is the record buffer length; it contains a positive integer specifying the length 
of the record buffer. 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is: 

RTVSEQ filnum . . . Produces a call with an absolute address for the parameter list 

RTVSEQ* filnum . . . Produces a call with a relative address for the parameter list as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program, as described 
later in this section. 

Error considerations (reqind) are as follows: 

• RTVSEQ sets bits 14 and 15 (rejecting the request) if: 

-filnum < 

-recptr < 
o RTVSEQ sets bit 15 (rejecting the request) if: 

-filnum is released or not defined (bit is also set). 

-The user attempts to remove a record from a locked file without the proper combination 
(bit 1 is also set). 
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-End-of-file is detected (bit 3 is also set). 

-A mass storage error occurs (bit 7 is also set). 

-The user attempts to remove a record from an indexed file (bit 11 is also set). 

-An unprotected request tries to remove a record from a protected file (bit 13 is also set). 

RTVSEQ sets bit 1 (but does not reject the request) if the size of the record read was less than the 
full record length. RTVSEQ sets bit 5 (but does hot reject the request) if the record has been removed. 

If a mass memory error occurs while attempting to release space, the message 

F.M. ERROR 1 

is delivered to the comment device. 



3.2.3 EXAMPLES OF SEQUENTIAL REQUESTS 

A computerized supermarket stores the orders of its customers in the new orders file, sequentially in 
the order in which the orders are phoned in. The FORTRAN code in Example 4 is part of the code 
executed each time a new order is entered into the computer system. Note that the record data is 
stored beginning at word 2 of the record to allow for the header word. 



EXAMPLE 4: 



Program 

COMMON INPBUF-CEfim 

DIMENSION IRECPT-CE} n IREl3BF-ClS} 1 IRECBF-[5fiS> 

DIMENSION IDATA-C2SM} 

EQUIVALENCE -CIDATA-CU-, IRECBF-C2}} 



C TRANSFER CUSTOMER NAME-.L0CATI0N CODE-, 

C ROUTE NUMBER-, AN]) ITEMS ORDERED FROM INPUT 

C BUFFER TO RECORD BUFFER 

DO 1DD I=1t2A4 
1D0 IDATA-CI>=INPBUF-CI} 
C STORE RECORD INTO NEW ORDERS FILE 

IFLNUM=S 

CALL STOSE<HlFLNUM- 1 IRECPT- 1 IRECBF-,SfiS.,IRE<2BF 1 IRE<2ID} 
C CHECK FOR ERRORS 

IF -CIREfllD.LT.D} GO TO TDDD 



Comments 



285-word output buffer reserved. 

Data starts at word 2 of buffer to 
reserve word 1 for header. 



9000 is label of user's error 
recovery program. 
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In example 5 the new orders file described in Example 4 is processed to list all orders to be 
delivered on a given route. The records in the file are retrieved sequentially. When a record is found 
which corresponds to the given delivery route, the record is removed from the new orders file and 
stored in the routed orders file. 

The tests for end-of-f ile and previous record removal appear before any checks on the contents of the 
record buffer, since it must first be ascertained that a record was actually retrieved. Records are 
removed via direct retrieval, using the record pointer returned from the File Manager in the 
sequential retrieve call. Note that the remove option code , bit 15 of the third parameter in the retrieve 
direct calling list, is set to one to indicate that record removal is requested. 



EXAMPLE 5: 



Program 



Comments 



DIMENSION IRECPT-C2>-,IRE(JBF-ClS>-,IRECBF-CSflS> 
C RETRIEVE RECORD FROM NEU ORDERS FILE 

IRECPT-C1}=0 

IRECPT{2}=0 
ID IFLNUM=S 

CALL RTVSE(2-CIFLNUn-,DiIRECPT-,IRECBF-,BflS-,IRE(3BF-,IRE(2ID> 
C CHECK FOR ERRORS 

IF -CIREQID.LT.D} GO TO TODD 



Record pointer must initially 
be set to 0. 



9000 is identifier of error 
recovery routine. 



C HAVE ALL RECORDS IN FILE BEEN READ 
IF-CAND-CIRE<2ID-,fl}NE.O} GO TO 5DD 

C WAS RECORD PREVIOUSLY REMOVED 

IF-CAND-CIRE(JID-,$e03-.NE.D} GO TO 10 

C IS ROUTE DIFFERENT FROM THE DELIVERY ROUTE 

C BEING LISTED 

IF -CIRECBF-C1S}.NE.IR0UTE} GO TO ID 



Checks status bit 3 (end- 
of-file) 

Checks status bit 5 



User data formatted 



C ROUTE MATCHES DELIVERY ROUTE BEING LISTED 
C REMOVE RECORD FROM NEU ORDERS FILE 

ED CALL RTVDIR-CIFLNUM-,$flDDD- 1 IRECPT-,IRECBFiBaS 1 IRE£2BF-,IRE(aiD> 
IF -CIREfllD.LT.Dl GO TO TODD 



Checks status bit 15 to find 
if record is to be removed; 
9000 also removes record 
routine. 



C PRINT INFORMATION ON DELIVERY ROUTE LIST 
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Program 



Comments 



C STORE RECORD IN ROUTED ORDERS FILE 

IFLNUn=17 

CALL STOSEt3-CIFLNUn-,IRECPTiIRECBF-,EflS 1 IRE(3BF-,IRE(2ID} 
C CHECK FOR ERRORS 

IF -CIREi2ID.lt. D> GO TO 1DD0 
C GO READ NEXT RECORD 

GO TO ID 
SDD CONTINUE 



3.3 INDEXED REQUESTS 



3.3.1 STORE INDEXED RECORD (STOIDX) 

Records may be stored indexed in a file once it is defined as indexed. A record is stored in the file by 
its key value; its record pointer is returned to the caller so that the record may be accessed directly. 
An indexed store is permitted in a locked file; the status word that is returned indicates the file was 
locked. 

If a file was defined indexed-linked more than one record may have the same key value. The second 
and third words of the record are reserved for mass storage address of the linked record. In last-in/ 
first-out (LIFO) mode, this is the address of the previous record; in first-in/first-out (FIFO) mode, 
this is the address where the next linked record will be stored. Since each indexed-linked record must 
have these two words reserved for the linking pointers, indexed-linked records must be at least three 
words long. 



General information for store indexed records is as follows: 



.15 



• The length of the record cannot exceed the specified maximum record length (2 - 1). 

o If the file is not indexed-linked, not more than one record with the same key value can be 
stored. 

o A record cannot be stored indexed if either the file is undefined or the file is not defined 
as indexed. 

• An unprotected program cannot store a record in a file which was defined by a protected 
program. 

• If a record is the first to be stored into an indexed-linked file with FIFO linking, the 
specified record length becomes the fixed record length for all subsequent records stored 
in the file. If the record is not the first and the file is indexed-linked with FIFO linking, 
the specified record length must be less than or equal to the length specified for the first 
record. (Even though the specified length of subsequent records may be less than the 
length of the first record, the fixed length will be used in storing all subsequent records.) 
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CAUTION 

The store indexed request processor assumes that 
three words preceding and one word following the 
record buffer are part of the user's program. 



The reason why the three words preceding the record buffer must be part of the user' s program is 
explained in the cautionary note in the Store Sequential Record section. The word following the record 
buffer must be part of the user's program because as each record is stored into a file defined to have 
FIFO linking, the File Manager creates an extra record which reserves the space to be used for 
storing the next record. Thus, the pointer to the next record to be stored is immediately available 
for storage in words two and three. The extra record is stored with a header word containing $8000 
which signifies that the record is an extra record created by the File Manager for a FIFO-linked file. 



The value $8000 is temporarily stored into the word following the record buffer. After the record is 
transferred, the original contents of this word is restored. As for the three words preceding the 
buffer, the caution is necessary to prevent possible problems in a multiprogramming environment. 

The store indexed record request specifies: 

The file number of the file where the record is being stored 

The key value of the record being stored 

A buffer for returning the record pointer 

A buffer for information to be stored as the record 

A temporary buffer for processing the request 

An indicator word denoting the request's status upon completion (Figure 2-1). 

The FORTRAN format for store indexed record call is: 



CALL STOIDX (filnum,keyval,recptr,recbuf, reclth,reqbuf,reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file into which 

a record is to be stored. 

keyval is the key value; it is an array of keylth words 
containing the key value of the record. 

recptr is the record pointer set by the File Manager. It must be numeric for index- 
ordered records; otherwise it maybe alpha-numeric. It is a two-word array 
which contains the mass storage address of the record just stored. 

recbuf is the record buffer; it is an array of reclth words containing the record to be 
stored. 

reclth is the record length. It contains a positive integer specifying the length of the 
record. If the record is the first to be stored into an indexed -linked file with 
FIFO linking, reclth becomes the fixed record length for all subsequent 
stores. If it is not the first store into the file, reclth must be less than or 
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equal to the length of the first record. (Even though reclth may be less than 
the length of the first record, the fixed length will be used in storing all 
subsequent records). 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is: 

STOIDX filnum . . . Produces a call with an absolute address for the parameter list 

STOIDX* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program, as described 
later in this section. 

Error considerations (reqind) are as follows: 

• STOIDX sets bits 14 and 15 (and rejects the request) if: 

-filnum < 0. 

-The record length > three words, 
e STOIDX sets bit 15 (and rejects the request) if: 

-The file is released or has not been defined (bit is also set). 

-The record is too long or (FIFO index-linked files only) the record is not the standard 
length of the first FIFO record (bit 2 is also set). 

-More than one record has this key and the file was not defined as index- linked (bit 4 is 
also set). 

-A mass memory error occurs (bit 7 is also set). 

-There is no more file record space to store records (bit 8 is also set). 

-The file was not defined as indexed (bit 11 is also set). 

-An unprotected program attempts to store a record in a protected file (bit 13 is also set). 

If the file is locked, the request is executed but bit 1 is set. 

If more records have the same key value for an index- linked file, the request is executed but bit 4 is set. 



3.3.2 RETRIEVE INDEXED RECORD (RTVIDX) 

Indexed records may be retrieved using that index (key value) after the file is defined as indexed and at 
least one record has been stored in the file. The file may have been defined by either a protected or 
an unprotected program. A record is retrieved from the file by means of its key value. The mass 
storage address of the record is returned to the caller so that the record may be accessed directly. 
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For update purposes, a record may be retrieved and the file locked with a file combination. More 
records may be retrieved from the locked file only if the same or no file combination is used. These 
retrieved and updated records may be restored in the locked file using the store direct record call; 
the same file combination must be used. An indexed retrieval, which attempts to lock an already 
locked file with a different combination, is queued; the request is not executed until the file is unlocked 
by the combination that currently locked it. 

An indexed retrieval without a file combination is permitted from a locked file; however, the status 
board indicates that the file was locked. Provision is also made for removing a record from a file as 
it is retrieved. The first n words of an n + m word record may be retrieved; if this is done, the status 
word indicates a short record was retrieved. 

If a record has a non-unique key value (i.e. , the file has index-linked records), the status word 
associated with the retrieval indicates that other records have the same key. To retrieve all the 
records in the same key value series, the requesting program should repeat the RTVIDX call (using 
the same key value) until the status word indicates no more records exist in this link. After a repeated 
retrieval starts (to retrieve all records with the same key), any new records being concurrently added 
to the link are ignored. 

General information for retrieving indexed record is as follows: 

It is not necessary to retrieve all the index -linked records. 

The first and subsequent records with the same key value can be re- retrieved by a new call 
or by re- initializing the current call (refer to the recptr parameter). 

A record cannot be retrieved indexed if the record was previously removed from the file. 

A record cannot be retrieved indexed if either the file or the key was not defined. 

An unprotected program cannot remove a record from a file which was defined by a protected 
program. 

Records in an indexed -linked file must be a minimum of three words in length. 

The retrieve indexed request specifies: 

• The number of the file from where the record is being retrieved 

• The key value of the record 

o The file combination if the file is to be locked or the record is to be retrieved from a locked 
file 

• Whether the record is to be removed from the file 

• A buffer for returning the record pointer 

• A buffer for receiving the record to be retrieved 

• A temporary buffer for processing the request 

• An indicator word denoting the request's status upon completion 
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CAUTION 

If a RTVIDX call is repeatedly executed to retrieve all 
records with the same key value from an indexed-linked 
file, the File Manager uses the information left in the 
request buffer and the record pointer at the end of one 
call as information for the next call. Hence, these 
parameters may not be altered between calls in the loop. 
If a record with a different key value is to be retrieved, 
the key value should be changed and the record pointer 
set to zero. The record length and record buffer con- 
tents of RTVSEQ may be changed if the user desires. 



The format for retrieve indexed record call is: 



CALL RTVIDX (filnum , keyval, filcom, recptr , recbuf , reclth, reqbuf , reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file from which 

a record is to be retrieved. 

keyval is the key value; it is an array of keylth words containing the key value of the 
desired record 

filcom is the file combination and the remove option; bits through 14 contain a non- 
zero number specifying the combination; bit 15 set to one indicates that the 
record is to be removed from the file. The combination is used to remove/ 
retrieve from a locked file or to lock the file while retrieving so that no other 
user disturbs the records being updated. 

recptr is the record pointer set by the File Manager. It is a two-word array which 
contains the mass storage address of the retrieved record. If the file is 
indexed-linked, bom words must initially be set to zero by the requestor. 

recbuf is the record buffer; it is a non-preset array of reclth words, where the File 
Manager transfers the retrieved record. 

is the record buffer length; it contains a positive integer specifying the length of 
the record buffer. 



reclth 
reqbuf 
reqind 



is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 



The Assembly language format is: 

RTVIDX filnum . . . Produces a call with an absolute address for the parameter list 

RTVIDX* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program, as described 
later in this section. 
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Error considerations (reqind) are as follows: 

• RTVIDX sets bits 14 and 15 (rejecting the request) if: 
-filnum < 0. 

-The record < 3 words in length. 

• RTVIDX sets bit 15 (rejecting the request) if: 

-The file is released or not defined (bit is also set) . 

-The user attempts to remove the record from a locked file (bit 1 is also set). 

-The record is removed or does not exist (bit 5 is also set). 

-A mass storage error occurs (bit 7 is also set). 

-The file is not indexed (bit 11 is also set). 

-An unprotected program attempts to remove a record from a protected file (bit 13 is also set). 

RTVIDX sets bit 1 but executes the retrieval request if the file was locked. If a mass memory error 
occurs while attempting to release space, the message 

F. M. ERROR 1 

is delivered to the comment device. 

RTVIDX sets bit 2 but executes the request if less than the full record was requested to be read. 

3.3.3 EXAMPLES OF INDEXED REQUESTS 

A computer system in a medical clinic includes in its files a patient data file, indexed by a special 
file security number. The FORTRAN code in Example 6 shows how a record is stored indexed into 
the file. The patient's file security number is in words 1, 2, and 3 of tiie array ISOCSC. The key 
value is not part of the record data in this case. 

EXAMPLE 6: 

Program Comments 

DIMENSION IREflBF-C12}-,IRECBF-[31J 
DIMENSION IRECPT-Ca>-,IS0CSC-[3} 



C PATIENT DATA HAS BEEN STORED IN IRECBF. 
C STORE RECORD IN FILE- 

IFLNUM=15 

CALL STOIDX-CIFLNUM-,ISOCSC-,IRECPTi IRECBF, 31 -,IRE<2BFiIREc2ID} 
C CHECK FOR ERRORS 

IF {IREC3ID.LT. D> GO TO SDOD 5000 is label of storage error 

recovery program. 

39520600 D 3-27 • 



A hospital laboratory computer system includes an indexed-linked file of laboratory test results. Each 
record in the file consists of the laboratory results for a given test for a given patient. The file is 
indexed by the patient's file security number. All the records for a given patient are FIFO-linked. 
The FORTRAN code in Example 7 is part of a program used to print a laboratory report on a given 
patient as requested by a physician. The retrieve indexed request is repeated until all records for the 
patient have been retrieved. 



EXAMPLE 7: 



Program 



Comments 



DIMENSION IRE(3BF-C15> 1 IRECBF-C31>-,IS0CSC-C3>-,IRECPT-C2> 



C SOCIAL SECURITY NUMBER IS IN ISOCSC ARRAY 
C PROCEED TO PREPARE LAB REPORT ON PATIENT 

IFLNUn=25 
C ZERO OUT RECORD POINTER ARRAY TO INDICATE 
C THE START OF A LOOP TO RETRIEVE ALL RECORDS FOR THIS KEY VALUE 

IRECPT-C1} = D 

IRECPT-CE} = D 



ID CALL RTVIDX-CIFLNUn-,IS0CSC-,D 1 IRECPT-,IRECBF- 1 31.,IREC2BF-,IRE<3ID> 
C CHECK FOR ERRORS 

IF-CIREfllD.LT.O} GO TO TODD 



9000 is label of retrieval error 
recovery program. 



C UAS RECORD PREVIOUSLY REMOVED" 
1 IF -CAND-CIREQIDi^aOJ.NE.D? GO TO ID 
C PROCESS DATA FROM THIS RECORD FOR REPORT 



Status word, bit 5 



C GO BACK TO READ NEXT RECORD 
I C UAS THIS THE LAST RECORD FOR THIS PATIENT 
1DD IF {AND-CIREQID-.$1D>.E(2.D} GO TO SDD 
GO TO ID 



Status word, bit 4 



SDD CONTINUE 



Last record in line already 
retrieved 
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3.3.4 RETRIEVE INDEXED-ORDERED RECORD (RTVIDO) 

Records may be retrieved indexed-ordered from a file once the file has been defined and it has been 
defined as indexed-ordered and at least one record has been previously stored indexed in the file. 
(Index- ordered key values are pure numerics only.) The file may have been defined by either a pro- 
tected or an unprotected program. Each record in the file may be retrieved indexed-ordered by 
repeatedly executing one RTVIDO call until an end-of-file indication is given. If it is desired to 
retrieve records commencing with the record with a specific numeric key value (or if this record does 
not exist, the first record with a larger key value), the first RTVIDO call retrieves the record in the 
file that has the first numeric key value higher than the one specified. The nth RTVIDO call retrieves 
the record in the file that has the highest numeric key value, and the n + 1st RTVIDO call is rejected. 
The status word indicates an end-of-file condition as the cause of the rejection. For each of the n calls, 
one record is retrieved. The record's key value is returned in keyval; the corresponding record 
pointer is returned in recptr so that the record may be accessed directly. If there are no records in 
the file, the first call produces an end-of-file indication. If the user program requires retrieval of 
all the records in the file, keyval should be set to the lowest possible value (e.g. , 1). 

General information for retrieving indexed-ordered record is as follows: 

o It is not necessary to retrieve all the records from the file. 

© The record with the lowest key value or the record with a specified key value (as well as 

all subsequent ordered records) can be re-retrieved either by a new call or by re-initializing 
the current call (refer to the recptr parameter) . 

• For update purposes, a record may be retrieved and the file locked with the file combina- 
tion. More records may be retrieved from the locked file only if the same or no file 
combination is used. These retrieved and updated records may be restored in the locked 
file using the store direct record call; the same file combination must be used. An 
indexed-ordered retrieval which attempts to lock an already locked file with a different 
combination is queued; the new request is not executed until the file is unlocked. 

e An indexed retrieval without a file combination is permitted from a locked file; however, 
the status word indicates that the file was locked. Provision is also made for removing a 
record from a file as it is retrieved. The first n words of an n + m word record may be 
retrieved; however, if this is done, the status word indicates a short record was retrieved. 

• If a record is retrieved and at least one more record exists with the same key value (which 
implies the file is indexed- linked), the status word indicates that more records exist with 1 
the same key value. The continued execution of the RTVIDO call retrieves all the records 
with this key value. Following these retrievals the File Manager proceeds as before. 

o A record cannot be retrieved indexed-ordered if either the file or the key was not defined. 
Moreover, an unprotected program cannot remove a record from a file which was defined 
by a protected program. 

The retrieve indexed-ordered request specifies: 

o The file number of the record from where the record is being retrieved 

o A buffer for returning the key value 

o The file combination, if the file is to be locked or the record is to be removed from a g 

locked file 
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Whether the record is to be removed from the file 

A buffer for returning the record pointer 

A buffer for receiving the record to be retrieved 

A temporary buffer for processing the request 

An indicator word denoting the request's status upon completion 

Records in an indexed -linked file must be a minimum of three words in length 



CAUTION 

If a RTVIDO call is repeatedly executed to retrieve 
records starting with a given key value, then the 
information left in the request buffer, the key value, 
and the record pointer at the end of a call are used 
by the File Manager for the next call. Hence, 
these parameters must not be altered between 
successive calls. The record length and record 
buffer contents of RTVSEQ may be changed if the 
user desires. 



The format for retrieve indexed-ordered record call is: 

CALL RTVIDO (filnum, keyval, filcom, recptr, recbuf , reclth, reqbuf , reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file from which 

a record is to be retrieved. 

keyval is the key value, it contains an integer equal to or less than the lowest numeric 
key value desired (but greater than any smaller keyval for a record not to be 
retrieved). Otherwise keyval contains a positive integer specifying the 
numeric key value of the desired record. Following the retrieval, keyval 
contains the actual key value of the retrieved record. 

filcom is the file combination and the remove option; bits through 14 contain a non- 
zero number specifying the combination; bit 15 set to one indicates that the 
record is to be removed from the file. The combination is used to remove/ 
retrieve from a locked file or to lock the file while retrieving so that no 
other user disturbs records being updated. 

recptr is the record pointer set by the File Manager. It is a two-word array which 
will contain the record pointer (mass storage address) of the record. 
Initially, both words must be set to zero by the requestor. 

recbuf is the record buffer; it is a non-preset array or reclth words, where the File 
Manager transfers the retrieved record. 

reclth is the record buffer length; it contains a positive integer specifying the length 
of the record buffer. 
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reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is: 

RTVIDO filnum . . . Produces a call with an absolute address for the parameter list 

RTVIDO* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program, as described 
later in this section. 

Error considerations (reqind) are as follows: 

• RTVIDO sets bits 14 and 15 (rejecting the request) if: 
-filnum < 0. 

-reclth < 0. 

-reclth < three words if this is an index-linked file. 

• RTVIDO sets bit 15 (rejecting the request) if: 

-The file is released or not defined (bit is also set). 

-The file is locked and an attempt is made to remove a record using the wrong combination 
(bit 1 is also set). 

-A mass memory error occurs (bit 7 is also set). 

-The file is not indexed-ordered (bit 11 is also set). 

-An unprotected program attempts to remove a record from a protected file (bit 13 is also 
set). 

RTVIDO sets bit 1 but executes ttie request if the file is locked with combination filcom. RTVIDO sets 
bit 2 but executes the request if less than the full record is requested. RTVIDO sets bit 3 but executes 
the request if end of file is found. 

If a mass memory error occurs while attempting to release space, the message 

F. M. ERROR 1 

is delivered to the comment device. 
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3.3.5 EXAMPLE OF INDEXED-ORDERED REQUEST 

The results of a psychological test have been coded and stored into an indexed-ordered file called the 
results file. Each record in the file contains test results for one subject. Each record is indexed 
by the age of the subject. All records for subjects with the same age are FIFO index-linked. The age 
groups are ordered by the key value age. A schematic diagram of the contents of the file is shown 
in Figure 3-1. 



J. J. JONES 
AGE 17 



M. BAILEY 
AGE 17 



B. ALSPACH 
AGE 17 



D. DAY 
AGE 18 



T 



L. PHILLIPS 
AGE 18 



B. SUBERI 
AGE 18 



1 






C. H. SEDQWICK 
AGE 70 


L. E. ROVNER 
AGE 70 





A. L. SHENK 
AGE 70 



Figure 3-1. Schematic Representation of Indexed -Ordered, Indexed-Linked File Example 
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The FORTRAN code in Example 8 shows part of a program to do a statistical analysis on the results 
from all subjects with ages 25 through 35. The record pointer array is initially set to zero. Each set 
of calls for a given value of IAGE retrieves the results for all subjects with that age. If there are no 
subjects with that age, the first record for a larger age will be retrieved. To be sure that only records 
for subjects aged 25 to 35 are included in the data to be analyzed, a test is made on IAGE after a record 
is retrieved. 



EXAMPLE 8: 



Program 



Comments 



DIMENSION IRECPT-C2>-,IRE(3BF-C12}-,IRECBF-C31} 



C INITIALIZE TOTALS FOR STATISTICAL CALCUL ATIONS" 
IT0T1=D 
IT0T11=D 



Declares 11 buffers, one 
for each age group 



IFLNUn=lDD 

IAGE=25 

IRECPT-C1} = 

IRECPT-C2} = 
10 CALL RTVID0-CIFLNUf1-,IAGEiD-,IRECPT-,IRECBF-,31-.IRE(2BF-,IRE(2I])> 
C CHECK FOR ERRORS 

IF-tlREOID.LT.O} GO TO TODD 
C HAS RECORD BEEN REMOVED 

IF-CAND-CIREt3ID-,$20}.NE.D} GO TO ID 
C CHECK THAT AGE IS WITHIN SPECIFIED RANGE 

IF -CIAGE. GT. 35} GO TO fc.00 
C PROCESS DATA FOR THIS RECORD 

IT0T1 =IT0T1 ♦ IRECBF-C12} 

IT0T2 =IT0T2 + IRECBF-C13} 



9000 is identifier of error 
recovery routine. 

Checks bit 5 to find end of 
linked records 



IT0T1D =IT0T10 + IRECBF-C21} 
C GO BACK TO READ NEXT RECORD 

GO TO ID 
C PRINT STATISTICAL RESULTS 
L-DD CONTINUE 
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3.4 DIRECT REQUESTS 



1 



!0 J 



3.4.1 STORE DIRECT RECORD (STODIR) 

The function of the store direct request is to update records. Records may be stored directly in a file 
once it is defined and the file has been locked by a retrieve request. A record is stored in the file 
I using the record pointer previously provided when the record was either stored or retrieved by non- 
direct methods. 

General information for the store direct record is as follows: 

• An update can be done only if the same file combination is supplied that was used to lock the 
file. This request also permits the file to be unlocked after the record has been updated 
and stored. 

• A record cannot be stored directly if the file was not defined, not locked, or if the file 
combination is incorrect. 

• An unprotected program cannot store direct because of the possibility of destroying a 
protected file by using an incorrect record pointer. 

The store direct record request specifies: 

The number of the file where the record is being stored 
The file combination previously used to lock the file 
Whether the file should be unlocked 
A buffer containing the record pointer 
A buffer of information to be restored as the record 
j) A temporary buffer for processing the request 

• An indicator word, denoting the request's status upon completion (Figure 2-1). 



The FORTRAN format for store direct record call is: 

CALL STODIR (filnum,filcom,recptr,recbuf,reqbuf ,reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file in which a 

record is to be stored. 

filcom is the file combination and the file unlock option. Bits through 14 contain a 
non-zero number which is identical to the combination that was used to lock 
the file; bit 15 set to one indicates that the file will be unlocked. 

recptr is the record pointer. It is a two-word array containing a pointer to the mass 
storage address where the record is to be stored. 

recbuf is the record buffer; it is an array of reclth words containing the record to be 
stored. 
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reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is: 

STODIR filnum . . . Produces a call with an absolute address for the parameter list 

STODIR* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program, as described 
later in this section. 

Error considerations (reqind) are as follows: 

• STODIR sets bits 14 and 15 (rejecting the request) if filnum < 0. 

• STODIR sets bit 15 (rejecting the request) if: 

-A file is released or not defined (bit is also set). 

-A file is not locked (bit 1 is also set). 

-A mass memory error occurs (bit 7 is also set). 

-The address for storing the record is not in FILMGR's disk space (bit 9 is also set). 

-A file is locked with the wrong combination (bit 10 is also set). 

-An unprotected program attempts to store into a protected file (bit 13 is also set). 



3.4.2 RETRIEVE DIRECT RECORD (RTVDIR) 

The function of the retrieve direct request is to provide: 

• A fast method of retrieving frequently accessed records 

• A method for retrieving records linked together by their record pointers in the user's own 
list structure 

Records may be retrieved directly from a file once the file is defined and at least one record has been 
stored in the file. The file may have been defined by either a protected or an unprotected program. A 
record is retrieved from the file through a record pointer previously provided when the record was 
either stored or retrieved by non-direct methods 
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General information for retrieve direct record is as follows. 

• The user may form any number of complex list structures as long as they conform to the 
File Manager file structure. One list structure is provided for indexed-linked files. 

• For LIFO-linked files, the record pointer of the last stored record with the same key value 
is stored by the File Manager in the second and third words of the record currently to be 
stored. These records may then be retrieved directly on a LIFO basis by referencing the 
second and third words of the last retrieved record as the record pointer. The end of 

the list is signified by the record pointer being zero (second and third words bom zero). 
For the FIFO-linked files, the File Manager stores the record pointer of the next record 
with the same key value to be stored in the second and third words of the record currently 
to be stored. These records may then be retrieved directly on a FIFO basis by refer- 
encing the second and third words of the last retrieved record as the record pointer. The 
end of the list is signified when the request indicator for the retrieve direct request indi- 
cates that the record does not exist. This condition occurs because the File Manager sets 
the removed flag in the extra record. 

• For update purposes, a record may be retrieved and the file locked with a file combination. 
More records may be retrieved from the locked file only if the same or no file combination 
is used. These retrieved and updated records may be stored into the locked file via the 
store direct record call, only if the same file combination is used. Note that a direct 
retrieve which attempts to lock an already locked file with a different combination is 
queued; it is not executed until the file is unlocked with the current file combination. 

• A direct retrieve without a file combination is permitted from a locked file; however, the 
status word indicates that the file was locked. Provision is also made for removing a 
record from a non-indexed file as it is retrieved (caution should be exercised on removing 
records which are part of a list structure) . The first part of a record of any desired 
length may be retrieved; however, the status word indicates that there was a short record 
retrieval. 

• A record may be retrieved but cannot be removed from an indexed file using a retrieve 
direct request. A record is not retrieved directly if the record was previously removed 
from the file. A record cannot be retrieved if the file is not defined. An unprotected 
program cannot remove a record from a file which was defined by a protected program. 

The retrieve direct record request specifies: 

The number of the file from where the record is being retrieved 

The file combination, if the file is to be locked or the record is to be retrieved from a 
locked file 

Whether the record is to be removed from the file 

A buffer containing the record pointer 

A buffer for receiving the record to be retrieved 

A temporary buffer for processing the request 

An indication word, denoting the request's status upon completion (Figure 2-1). 
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The FORTRAN format for retrieve direct record call is: 

CALL RTVDIR (filnum, filcom, recptr, recbuf, reclth, reqbuf, reqind) 

Where: filnum is the file number; it contains a positive integer identifying the file from which 

a record is to be retrieved. 

filcom is the file combination and the remove option; bits through 14 contain a 

non-zero number specifying the combination; bit 15 set to one indicates that 
the record is to be removed from the file. The combination is used to 
remove/retrieve from a locked file, or to lock the file while retrieving so 
that no other user disturbs the records being updated. 

recptr is the record pointer; it is a two-word array containing the record pointer mass 
storage address of the record to be retrieved. 

recbuf is the record buffer; it is a non-preset array of reclth words, into which the 
File Manager transfers the retrieved record. 

reclth is the record buffer length; it contains a positive integer specifying the length 
of the record buffer. 

reqbuf is the file request buffer; it is a non-preset array of 12 words which the File 
Manager uses to process the request. 

reqind is the file request status word. At the end of request processing, the File 
Manager sets the indicator bits as appropriate. 

The Assembly language macro format is: 

RTVDIR filnum . . . Produces a call with an absolute address for the parameter list 

RTVDIR* filnum . . . Produces a call with a relative address for the parameter list, as 

for a run-anywhere program 

Note that to use the macro call, an FLDF macro call must be included in the program as described 
later in mis section. 

Error considerations (reqind) are as follows: 

• RTVDIR sets bits 14 and 15 (rejecting the request) if: 
-filnum < 0. 

-Record length = words 

• RTVDIR sets bit 15 (rejecting the request) if: 

-The file is released or not defined (bit is also set). 

-The user program attempts to remove the record without the correct file combination 
(bit 1 is also set). 

-A mass memory error occurs (bit 7 is also set). 

-The user program attempts to remove an indexed file (bit 11 is also set). 

-An unprotected program attempts to remove the record from the protected file (bit 13 
is also set). 
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If the file is to be locked, RTVDIR sets bit 1 and executes the request. If the record requested is 
shorter than the stored record, RTVDIR sets bit 2 and executes the request. 

If a mass memory error occurs while attempting to release space, the message 

F. M. ERROR 1 

is delivered to the comment device. 

3.4.3 EXAMPLES OF DIRECT REQUESTS 

In a hospital system a file called the patient file has been defined by a protected program. Patient 
records have been stored into the file. 

The FORTRAN code in Example 9 is part of a protected program. In the program the file is searched 
for a given patient record. The file is then locked. This is necessary before the direct store request. 
The record is updated and stored back into the file via a direct store request. The file is also unlocked 
by the direct store request. 

Note that if the code in Example 9 were part of an unprotected program, the patient file could not be 
updated, since the store direct request would then be illegal. Even if the patient file were defined as 
indexed, and if the key of the found record were known, a store indexed request could not be used to 
store the updated record since the original record would still be in the file. The original record could 
not be removed by a retrieve indexed request from an unprotected program. 

EXAMPLE 9: 



Program 



Comments 



INTEGER FILNUM-,FILC0MiRECPTR-,RECBUF-,RECLTH-,RE<3BUF-,REQIND-,PATL0C 

DIMENSION RECPTR-C5> 1 RECBUF-CM1> 1 RE0BUF-C15> 
C RETRIEVE DESIRED RECORD FROM FILE ID 

FILNUM = ID 
C SET THE FILE COMBINATION TO ZERO -CNO FILE COMBINATION} 



FILCOM = D 
C CLEAR RECORD POINTER TO INITIALIZE THE RETRIEVE REQUEST 

RECPTRO} = D 

RECPTR-C2} = D 
C USER TO RETRIEVE A RECORD 41 UORDS LONG 

RECLTH = 41 
C RETRIEVE RECORDS SEQUENTIALLY FROM FILE ID LOOKING FOR 
C PATIENT RECORD 
1DDD CALL RTVSEO-CFILNUM-,FILC0M-,RECPTR-,RECBUF-,RECLTH-, 

RE(3BUF-,REQIND> 
C GO TO T^fi IF SEQUENTIAL RETRIEVE ERROR 

IF -CREC2IND.NE.0} GO TO I^Tfi 



©3-38 



More than one error recovery 
routine is needed. 
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Program Comments 

C 
c 
c 

C THE RECORD FORMAT IS THE RECORD LENGTH IN WORD li TUO TUO- 

C UORD RECORD POINTERS IN UORDS 2 THRU S, THE PATIENT LOCAT" 

C ION IN UORD b-, THE MEDICATION CODE IN UORD ?, AND PATIENT 

C DATA IN UORDS fl THRU 41 

C 

C IF PATIENT LOCATION DOES NOT MATCH. CHECK NEXT RECORD 

IF -CRECBUF-Ct>.NE.PATLOC> GO TO 10QO 
C 

c 
c 

C PATIENT RECORD UITH THE GIVEN PATIENT LOCATION FOUND 

C GENERATE UNIflUE FILE COMBINATION TO LOCK FILE 

C NOTE**ONLY THIS METHOD SHOULD BE USED TO GENERATE FILE COMBINATIONS** 

2000 ASSIGN 2000 TO FILCOM 
C 
C 
C 

C LOCK THE FILE FOR UPDATE 

CALL L0KFIL-CFILNUM-,FILC0M-,RE<2BUF,REflIND} 
C GO TO 11*17 IF LOKFIL ERROR 

IF -CREflIND.NE.OJ- GO TO 1117 
C 
C 
C 
C UPDATE PATIENT RECORD UITH MEDICATION CODE 

RECBUF {7} = MEDCOD 
C SET FILE COMBINATION TO UNLOCK THE FILE AFTER THE UPDATE 

FILCOM = FILCOM + SflOOO 
C STORE UPDATED RECORD FOR PATIENT DIRECTLY BACK INTO FILE 10 

CALL STODIR-CFILNUM -.FILCOM -.RECPTR-, RECBUF -,REflBUF-,REOIND> 
C GO TO lilt IF DIRECT STORE ERROR 

IF -CRE<3IND.NE.0> GO TO lilt 
C 
C 
C 
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In Example 5 we had an example of a direct retrieve request used to remove a record from a non-indexed 
file. Note in this example that if file 5 had been an indexed file, the direct retrieve request could not 
have been used to remove the record. If file 5 were indexed and if the key value were contained in the 
record data, the key value could be extracted from the record and used to retrieve and remove the 
desired record by means of a retrieve indexed request. 

Statement 20 in the code listed in Example 5 would be changed in the case of an indexed file. The 
corresponding FORTRAN code for an indexed file is shown in Example 10. 

EXAMPLE 10 : 

C REMOVE RECORD FROM NEU ORDERS FILE. 
C KEY VALUE IS CONTAINED IN 
C UORDS 41 AND M2 OF RECORD 

ED CALL RTVIDX-CIFLNUMiIRECBF-Cmii^flDDDiIRECPTiIRECBFT 

2flS-,IRE(3BF-,IRE<2ID> 
C CHECK FOR ERRORS 

IF-CIREfllD.LT.Dl GO TO TDDO 



3.5 ASSEMBLY LANGUAGE COMMUNICATION WITH 
THE FILE MANAGER 



3.5.1 CALLING SEQUENCES WITHOUT USE OF MACROS 

Calling sequences written in Assembly language which are intended to communicate with File Manager 
subprograms may have the following form, where flrqst is the name of a File Manager routine and 
flrqst is declared as an external in the user's program. 



LOC 

LOC+1 

LOC+2 

LOC+3 

LOC+4 



RT J flrqst 

(RTJ flrqst is a two- word instruction) 

Address of argument 1 

Address of argument 2 

Address of argument 3 



LOC+N 
LOC+N+1 



Address of argument N 
Program resumes 
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3.5.2 USE OF FLDF MACROS 

Macros from the macro library, described earlier, may be used to generate File Manager calls. 
When one or more macro is used in a program to make a File Manager call, an FLDF macro call 
must be included in the program unit. The FLDF macro does not generate executable code; there- 
fore the call to FLDF must be positioned in the program so that it will not be executed. For example, 
it could be placed in a subprogram before the first entry point, or at the end of a program, or within 
the body of the program preceded by a jump instruction to bypass the nonexecutable code in the macro. 
The format of me FLDF macro call is: 



FLDF 



filnum, maxrl, lu, numekv, keylth, filcom, reclth 



Each parameter in the calling list may be a constant or a variable name. If it is a variable name, it 
must correspond to the actual value desired, as in an EQU statement, and not to the location containing 
the desired value. The macro defines the locations by affixing two letters to the front of the file num- 
ber parameter (filnum). For this reason, filnum cannot be more than four characters long. The 
macro places the values of the appropriate locations into the FLDF calling list. The locations defined 
by the macro are as follows: 

Comments 



Parameter 


Location 


filnum 


FN filnum' 


maxrl 


MR 'filnum' 


lu 


LU'filnum' 


numekv 


NK'filnum' 


keylth 


KL'filnum' 


filcom 


FC filnum' 


reclth 


RL'filnum' 


reqbuf 


RB'filnum' 


recptr 


RP'filnum' 


reqind 


Rl'filnum' 



These are initially equal to 12, 0, and 0; 
therefore they need not be specified in 
the FLDF macro call (above) since they 
are fixed constants. 

Where: filnum is the four-character file number parameter 

To change a parameter's value, the value of the contents of the corresponding macro-defined location 
must be changed. Recptr is initially set to zero by the macro. Thereafter, the user must set recptr to 
zero for requests that require it. If more than one file is defined, more than one macro may be used. 
Otherwise, the values of the parameters in the FLDF macro must be changed to correspond to the new 
file. Whenever a File Manager request is made, all the values needed by the request must have been 
previously stored in the corresponding locations defined by the macro. If the lu parameter in the FLDF 
calling list is blank, the logical unit is set to 8, the normal library unit. 

The following is an example of a program making File Manager requests using two files with the 
corresponding FLDF macros. The macro expansion is included in the following listing: 
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Program 



Comments 



* DEFINE A FILE 
CONT DEFFIL 1 

EXT DEFFIL 
RTJ+ DEFFIL 



DEFINE A FILE 



L ADC 



FNlTMRl-iLUlnRBlnRIl 



Defined by MAC FLDF. (below) 



NOTE 

The same parameters used to establish 
a call using the CALL FORTRAN request 
must also be used here; e. g. , for DEFFIL, 
the parameter list must be filnum, maxrl, 
lu, reqbuf, reqind. For STOSEQ, the 
parameter list must be filnum, recptr, 
recbuf reclth reqbuf reqind. Param- 
eters that generate macro code must be 
in the defining statement and must be 
separated by commas in that statement; 
however, parameters that do not generate 
macro code and that follow after all other 
parameters that do generate such a code 
may be omitted. All parameters are 
included in the ADC sequence. 



TAKE STATUS OF THE FILE 
STATFL 1 



t< 



LDA 

IFC 
AND 
EIF 
IFC 
SAZ 

jnp 

EIF 



RI1 
•iNE- 

nNE- 



STATUS A FILE 



MASK STATUS 



NOTHING TRUE 
JUI1P TO BD IF ANY TESTED 
STATUS BITS ARE SET 



Parameter list; fw, mk, bd 
(see below) 
fn parameter 

ml parameter 



bd parameter 



STORE SEQUENTIALLY INTO THE FILE 
STOSEfl l-iBUFIN-,21* 



fEXT 
IFC 
LDA 



t« 



STA 

EIF 
RTJ + 



lADC 



STOSEfl 
2M-.NE-, 
=X2M 

RL1 



STOSEfl 



STORE IN 
SEQUENTIAL 
FILE 1 



FNItRPIiBUFINiRLIiRBIiRII 



t Macro expansion 



Only the reclth needs to generate 
code. Other parameters are 
constants. 
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Program 



Comments 



DEFINE A FILE 
DEFFIL 2 
EXT DEFFIL 

RTJ* DEFFIL 



t< 



DEFINE A FILE 



ADC FN2-inR2-.LU2iRB2-.RI2 



EflU NUriEKV 



DEFINE SKELETON PARAMETER LIST FOR FILE 1 
MAC FLDF li € 13-,3nl-,0 1 2M 
ADC 1 



^FNl 
MR1 

LU1 
LU1 



t« 



RBI 

RI1 
NK1 
KL1 
FC1 
RL1 
^RPl 



ADC ^3 

IFC -.Ed- 
ADC fl 

EIF 

IFC -iNE- 
ADC 

EIF 
BZS RB1-C12} 

BZS RIl-Cll 

ADC 3 

ADC 1 

ADC D 

ADC 2M 

ADC D-.D 



If lu is undefined, lu8 is 
assigned. 



12 word processing buffer 
Status word must initially 
be zeroed. 



Two word record pointer 



DEFINE SKELETON PARAMETER LIST FOR FILE 2 



t« 



MAC2 
FN 2 
MR2 

LU2 



LU2 

RB2 
RI2 
NK2 
KL2 
FC2 
RL2 
RP2 



FLDF 
ADC 2 
ADC 13 

IFC nE(3- 
ADC fl 

EIF 

IFC -.NE- 
ADC 

EIF 
BZS RB2-C12> 
BZS RI2-C11 
ADC NUM 
ADC 1 
ADC D 
ADC 31 
ADC QnD 
END 



NUMEKV 
2-.13-.tD-.1-.D-.31 



See comments for file 1 skeleton 



t Macro expansion 
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3.5.3 A MACRO TO TEST REQUEST INDICATOR BITS ON RETURN FROM A FILE 
MANAGER CALL 

The file status macro, STATFL, provides the user with an easy method of getting the request indicator 
word, masking specified error conditions, and giving control to a specified error routine if errors 
are present. A file status of zero implies that no errors occurred on the last file request. Forms of 
the macro call are as follows: 



Where 



STATFL 


fn, 


mk, bd 


STATFL 


fn 




STATFL 


fn, 


mk 


STATFL 


fn, 


mk, bd 


5: In 


is 


the file 


mk 


is 


the ma 



the mask that is used to form the logical product with the request indicator. 
(If mk is left blank, only the status is placed in the A register. ) The 
terminator, such as the dash (-) in the fourth example, determines the 
addressing mode used on the AND instruction and may be a -, +, *, or blank. 

bd is the program label where control is given if the logical product of mk and the 

request indicator is non-zero. If bd is left blank, no code will be generated 
to test the request indicator status. In this case the logical product of the 
request indicator and the mask is left in the A register at the end of the 
macro and may be tested by the user. 
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TIME REQUIREMENTS 



4 



In this section, the access rate equations are given in terms of the number of accesses for each 
storage/retrieval method and the transfer rate for the mass memory device. Next, an example 
illustrates the calculation of the access rates. The equations for the number of accesses and transfer 
rates are derived in Appendix D from the definition of the file structure in Appendix B and the 
characteristics of the mass memory devices (disk and drum). 



DEFINITIONS 

The following terms will be used in this section: 

• Seek time — The time required for the disk arm to travel from a given disk cylinder to the 
disk cylinder to be accessed. (A drum has no seek time. ) 

• Latency — The time required for a mass memory device to travel from the data to be 
accessed to the read heads within a given track. 

To the definitions given in Appendix C, the following symbol definitions are added: 



AR — Access rate 

NA — Number of accesses 

TR — Transfer rate 

SS — For sequential store 

NSR — For next sequential retrieve 

ASR — For any sequential retrieve 

IS — For indexed store 

IR — For indexed retrieve 

DS — For direct store 

DR — For direct retrieve 

DK — For disk 

DKR — For disk read 

DKW — For disk write 

DM — For drum 

f(ro) — Remove option function (a one if the record is to be removed, otherwise zero) 
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SEEK — Average seek time of the disk 



LAT — Average latency of mass memory device 

LAT — Maximum latency of mass memory device 

TWR — Transfer word rate of mass-memory device 

IUNF — Initial usage for non-indexed file 

IUIF — Initial usage for indexed file 

TUNF — Terminal usage for non- indexed file 

TUIF — Terminal usage for indexed file 

NFISSS — Number of file information segments with the same scatter code 



ASSUMPTIONS 

c 

The access rate equations are approximations in that they assume the File Manager software is in core 
and its overhead is negligible, and that the initial and terminal usage (see Sections D. 1.4 and D. 1.5) of 
a file can be neglected if a fairly large number of records are accessed. Note that it is also assumed 
that the record lengths are small (e.g. , RL < 93) for the disk transfer rates, that there are no key 
information segment overflow blocks (to simplify the derivation), and that the assumptions of Section 
C.1.2 are true. 



4.1 ACCESS RATE EQUATIONS 

The access rate for any of the storage/retrieval methods is found by taking the product of the number of 
accesses required by that method and the transfer rate of the mass memory device, i.e. , 

AC = NA • TR 



4.1.1 SUMMARY OF ACCESS EQUATIONS 

| The equations in this section are derived in Appendix D. Note that some of the access rate equations in 
this section give access rates for record storage. These equations assume that any needed space will 
be available in the file space list. If this is not the case, additional accesses from the file space pool 
will be necessary to obtain the space. These additional accesses may significantly add to the number of 
accesses. To maximize use of the file space list and thereby minimize the number of file space pool 
accesses, refer to Section 2. 

§ The following summary is based on derivations from Appendix D and assumptions from the beginning of 
this section. 

1. Number of accesses to store a sequential record as a part of a loop to store all the 
sequential records in one file record block: 

NA„„ = 1 + RL 



SS MAXR L 
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2. Number of accesses to retrieve the next sequential record: 

NA NSR = 1+f(TO) 

3. Average number of accesses to retrieve any sequential record: 

NR , 
NA ASR = T + f(r °> 

4. Number of accesses to store an indexed record as a part of a loop to store all the indexed 
records in a file record block: 

NA_„ = 3 + RL 



IS MAXRL 

Number of accesses to retrieve an indexed record: 



NA = 2 + 2 • f(ro) 



Number of accesses to store a direct record: 



NA„ = 1 
DS 

7. Number of accesses to retrieve a direct record: 



NA DR = * + f(r0) 



4.1.2 SUMMARY OF DISK/DRUM TRANSFER RATES 

The following derivations are from Section D.2 with assumptions from the beginning of this section. 

1. Average transfer rate for disk read: 

KR 2 
TR DKR = KR 1 + ~96~ (RL ~ 1) ms/accesst 



2. Average transfer rate for disk write: 

KW 2 
TR DKW ~ KW 1 + ~96~ (RL " X) ms/accesst 

t Approximate constant values are: Constant Symbol 853/854 Flexible Disk SMD 



KR 


123 


344 


39 


KR 2 


25 


167 


17 


KW 


148 


511 


56 


KW 2 


50 


334 


34 
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3. Average transfer rate for drum: 



TR = 8 + . 008 • RL milliseconds/access 



4.1.3 ACCESS RATE EQUATIONS FOR DISK 

From above: 

1. Access rate of sequential store as a part of a loop to sequentially store records in the file: 

KW, 



/ RL \ / * W 2 \t 

ar ssdk ~ I 1 + ^XiRTJ ( KW i + ^T (RL " 1] ) 

2. Access rate of next sequential retrieve: 

AR NSRDK ^ ( + «™>) ( KR 1 + TiT< HL - ^ 

3. Access rate of any sequential retrieve: 

AR ASRDK " (f + «"») ( KR 1 + ^F< RL " 1) ) t 



NOTE 

In equations 4 and 5 it is assumed that the length of 
any KIS block does not exceed 96 words. The time to 
access one word on 853 disk is 12.8 microseconds. The 
time to access one word on drum is 8 microseconds. 
If the KIS block size is large, the total access rate 
may be significantly increased. 

Consider the extreme case of a KIS block size equal 
to 12, 000 words: Refer to Appendix B. The time 
needed to access all words in the KIS block would 
be 154 milliseconds if using an 853 disk, or 96 mil- 
liseconds if using a drum. 



Constant Symbol 


853/854 


Flexible Disk 
344 


SMD 


KR„ 
1 


123 


39 


KR 2 


25 


167 


17 


KW 


148 


511 


56 


KW 2 


50 


334 


34 
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4. Access rate of indexed store as a part of loop of indexed stores: 



( 3+ M^i:)( KW 1 + i6 1(RL - 1 ) t 



AR ISDK ^ |3 + 

5. Access rate of indexed retrieve as a part of a loop of indexed retrieves: 

AR IRDK " ( 2 + 2 * f<r °') ( KR 1 + "ST < RL - X ») + 

6. Access rate of direct store: 

KW 

AB D8DK"' KW i + -ir (BL - 1 > t 



7. Access rate of direct retrieve: 

KR 
AR DRDK * ( (1 = f(r0) ) ( KR 1 + "?T< RL - X) ) + 



4.1.4 ACCESS RATE EQUATIONS FOR DRUM 

From above: 

1. Access rate of sequential store as a part of a loop of sequential stores: 



AR SSDM =( 1 + M^l)( 8 + - 008 ' RL ) 



2. Access rate of next sequential retrieve: 



AR NSRDM = (1+£<r °» (8 + -008-RL) 



3. Access rate of any sequential retrieve: 

AR ASRDM = (lT + f(r °>) < 8 + - 008 * RL) 



t Approximate constant values are: Constant Symbol 853/854 Flexible Disk SMD 



KR 


123 


344 


39 


KR 2 


25 


167 


17 


KW 


148 


511 


56 


KW 2 


50 


334 


34 
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4. Access rate of indexed store as a part of a loop to store indexed records: 



AR ISDM = ' 3 + 



5. Access rate of indexed retrieve: 



( 3 + dl^)< 8 + - 008 - RL > 



AR IRDM = {2 + 2 * f < ro » < 8 + • 008 • RL > 



Access rate of direct store: 



AR DSDM = 8 + .008-RL 



7. Access rate of direct retrieve: 



AR DRDM = (1 + f(r0)) (8 + ' 008 ' RL > 



4.2 EXAMPLE OF ACCESS RATE CALCULATIONS 

One hundred records are retrieved, indexed, updated, and stored direct on disk. What is the time 
required if the record length is 19 words ? 



| From above: 



AR IRDK -<2 + 2-f(ra»U2S +s (RL-l>. 



(l23 + | (RL - 1,) 
(l23 + § (19 - 1)) 



~ (2 + 0) 1 123 + — (19 - 1) 



256 MS/IS 



I From above: 



AR DSDK " 148 + I < RL - J > 



50 
M8 + - (19-1) 



Therefore , the total time (T) 
required for this example is: 



«157 MS/DS 

T « 100 (256 + 157) 
T «41.3 seconds 
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4.3 MINIMIZATION OF TIME REQUIRED FOR INITIAL FILE ACCESS 

The access times derived above do not include accesses due to the initial usage of a file as described in 
Appendix D. These may be significant if a large number of different files are accessed. To minimize 
the number of initial accesses, the following procedure may be incorporated into system initialization. 

The search to obtain a file's FIS can be minimized if the files are first defined in a particular sequence. 
This can be done by placing the FISs of the files with the same hash code in the same FIS block; there 
are 47 FIS pointers in the FIS directory and 17 FISs in the FIS block. Assuming a system has less 
than 800 (47 x 17 = 799) files, all the FISs with the same hash code can be placed in the same FIS block 
by defining the files in the following order: 



1. 


Files 1, 


48, 


95, . . 


. , 753 


(17 defines) 


2. 


Files 2, 


49, 


96, . . 


. , 754 


IT 


3. 


Files 3, 


50, 


97, . . 


. , 755 


M 



47. Files 47, 94, 141, .... 799 (17 defines) 

If there are more than 800 files, a similar procedure can be developed. 

If a user wishes to define the files dynamically, an initialization program can define them as explained 
above and then release them. Since the space for FIS blocks is not re -used, the order will then be 
determined and the number of accesses (two) to retrieve any FIS will be minimized. 
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GLOSSARY 



A I 



D 



BSBB 



DEFFIL 

DEFIDX 

FIFO 

File 

File request buffer 



File request indicator 
word 



File space list 
File space pool 

FILMGR 
filnum 

FIS 

FIS directory 

Header word 
Indexed file 

Indexed-linked file 



Define file request. 

Define file as indexed request. 

First-in/first out 

A collection of related records treated as a unit 

An array of 12 words located in the user's program, which is used to 
process a file manager request. 

A location specified by the user when making a file manager request. 
On return from the File Manager, each bit of this word indicates some 
condition (e. g. , an error) that occurred while the request was processed. 
Refer to Section 3.1.1. 

One or more blocks of available mass memory space in which each seg- 
ment within a given block has the same length. There is one file space 
for each file manager mass memory unit. 

All available file space which is not included in the file space list. A 
segment of space in the file space pool will have a length not included in 
the file space list. There is one file space pool for each file manager 
mass memory unit. 

The core-resident supervisor program of the File Manager 

File identifier 

File information segment; contains coded information identifying the file 
and describing its structure and current condition. 

A set of pointers. Each entry points to the first of a set of FIS blocks on 
mass memory; all the FIS blocks in the set are for files with a given file 
number scatter code. 

The first word in a file record 

A file in which each record is stored according to a key (e. g. , social 
security number). A record in an indexed file may be retrieved by 
indicating its key value. 

An indexed file in which there may be more than one record for a given key 
value (e. g. , age). All records with the same key value may be retrieved 
by specifying the key (e.g., all records for persons age 25). 
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Indexed-ordered file 



KIS 

KIS block 
KIS directory 

LIFO 

Locked file 
Logical unit 
LOKFIL 
MS Record 
MSA 

Parameter list 
Pseudo disk 

Record buffer 
Record pointer 

RELFIL 
Retrieve 
RTVDIR 
RTVIDO 
RTVIDX 
RTVSEQ 
Sequential file 



A file in which each record has a corresponding numerical key (for 
example, code for date). In an indexed-ordered file, a set of records may 
be retrieved by specifying an interval of key values (e.g., all records for 
June 1972 through April 1973). 

Key information segment; the KIS contains the key for a given file record. 
If the file is indexed-linked, KIS contains one or two record pointers. 

A group of KISs stored together on mass memory 

A set of pointers; each entry points to a KIS block for a particular key 
scatter code 

Last-in/first-out 

A file into which information cannot be written until it is unlocked 

Identification of peripheral device (true device or pseudo device) 

Request to lock file 

Mass storage 

Mass storage address 

List of parameters required by the File Manager request 

Portion of a disk defined as a single logical unit (a pseudo disk is 
usually composed of 32K contiguous sectors) 

A buffer specified by the user that will contain a file record 

A two-word mass-storage address that points to a file record on mass 
storage 

Request to release a file 

The process of finding a record and reaching it into core 

Request to retrieve record using direct access 

Request to retrieve record using index-ordered key value 

Request to retrieve record using key value 

Request to retrieve record sequentially 

A file in which each new record is added immediately following the last 
record stored in the file. These records must be retrieved in the same 
sequence as they were stored. 
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STODIR 
STOIDX 
Store direct 
STOSEQ 
UNLFIL 



Request to store a record at a specified mass storage 

Request to store a record using a key value 

A type of file manager request allowing file record updates 

Request to store a record sequentially 

Request to unlock a file 
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FILE STRUCTURE 



B I 



2D 



j$n..'T.t 



•- "^-■- -»- 



Each defined file has a file information segment (FIS) that points to file record blocks (FRBs). An FRB 
contains file records and can be searched sequentially to access desired record(s). Alternately, a key 
information segment (KIS) can be used via the FIS to access one record randomly without searching 
through all the records. This appendix discusses each of these structures in detail. 



B.l FILE INFORMATION SEGMENT STRUCTURE 

The file information segment (FIS) structure, located on mass memory, is composed of one FIS 
directory and zero or more FIS blocks (see Figure B-l). This is a directory to records, not the 
records themselves. For indexed files, a similar directory is kept in the KIS directory (discussed 
below). Information to /from this structure is obtained via five core-resident parameters: 

• FIDSEC is the FIS directory's sector address. 

• NWFISD is the number of words in the FIS directory (multiple of 96). 
o FIBLSA is the sector address of the last FIS block. 

• FIBNIX is the index to the next available FIS. 

> e NWFISB is the number of words in a FIS block (multiple of 96). 



FIS 
DIRECTORY 



NWFISD 




NWFISB 



Figure B-l. File Information Segment Structure 
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I B.l.l FILE INFORMATION SEGMENT DIRECTORY 

The FIS directory of NWFISD words is created on mass memory when the first file is defined. Its 
sector address is given by the core-resident parameter FIDSEC. The directory is composed of: 

• A two-word header, which contains the sector address of the first FIS block (a zero 
indicates there are no FIS blocks) and a word reserved for future use 

• Up to ["(NWFISD - 2)/2~] two-word FIS pointers 

Utilizing the file number, modulo L(NWFISD-2)/2J , for a scatter code, each pointer points to the first 
FIS with a scatter code corresponding to the pointer's relative position in the FIS directory. If a FIS 
pointer (both words) is zero, there are no FISes for that particular scatter code. The FIS pointer has 
I the same format as a record pointer (see Section 2). 



| B.1.2 FILE INFORMATION SEGMENT BLOCK 

A FIS block of NWFISB words is created on mass memory whenever space is needed to store a newly 
defined FIS. Its sector address is given either by the FIS directory (if it is the first FIS block) or by a 
previously allocated FIS block. The block is composed of: 

• A header word, containing the sector address of the next FIS block (a zero indicates there 
are no more FIS blocks) 

I • Up to [(NWFISB - 1)/16J FISs (see Section B. 1.3) 

There are also two core-resident parameters, FIBLSA and FIBNIX, which give the sector address of 
the last FIS block and the index to the next available location in the last FIS block respectively. 



| B.1.3 FILE INFORMATION SEGMENT 



A 16 -word FIS is stored into a FIS block whenever a file is defined; its two-word mass memory address 
is given by a FIS pointer in either the FIS directory (if it is the first FIS with a particular scatter code) 
or a previously stored FIS. Note that once a file is defined, its FIS exists permanently, even if the 
file is released. A FIS is composed of the following: 



Word Mnemonic Description 

SANFIS Sector address of next FIS with the same scatter code (if zero, there are 

no more FISs for this particular scatter code) 

1 IXNFIS Index into SANFIS to next FIS with the same scatter code 



t Where |_xj is the greatest integer less than or equal to x. (see Section C.4.2), 
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Word Mnemonic Description 

2 FILENO File number 

3 FRBFSA Sector address of the first file record block (a zero indicates there are 

no file record blocks) 

4 NRLFRB Number of records stored in the last FRB 

5 FRBLSA Sector address of the last file record block 

6 FRBNIX Index to the next available location in FRBLSA 

7 KIDSEC Key information segment (KIS) directory's sector address (a zero indicates 

there is none) 

8 KIDSIZ KIS directory's size in sectors 

9 KIBSIZ KIS block size in sectors (a zero indicates the file is not indexed) 

10 KEYLTH Key length in words (a zero indicates the file is not indexed) 

11 NUMEKV Number of expected key values (a zero indicates the file is not indexed) 

12 FIFORL Fixed record length for indexed-linked FIFO file (a zero indicates that the 

file is not indexed-linked FIFO) 

13 NUMFRB Number of file record blocks currently assigned to the file 

14 FRBSIZ File record block size in sectors (bits through 8) 

FISIND FIS indicator with the following definition: 

Bit 13 is File is indexed-linked LIFO. 
1 File is indexed-linked FIFO. 

Bit 14 is File is not indexed-ordered. 
1 File is indexed-ordered. 

Bit 15 is File is not indexed-linked. 
1 File is indexed-linked. 

15 FISFLG FIS flag with the following definition: 

Bits 0—6 Logical unit for allocating FRBs 

Bits 7—13 Logical unit for allocating the KIS directory and KIS blocks 

Bit 14 is Defined by an unprotected program 
1 Defined by a protected program 

Bit 15 is File is released. 
1 File is defined. 
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A six -word header is appended to a FIS when the FIS is in core. A core FIS header is composed of the 
following: 



Word 


Mnemonic 





ANCFIS 


1 


SECFIS 


2 


IDXCHC 



ADRKID 
FILCOM 
FILCLK 



Description 

Address of next core-resident FIS (a zero indicates this is the last) 

Sector address of the FIS 

Index and change flags with the following definition: 

Bit is FIS has not been changed. 

1 FIS has been changed. 

Bit 1 is KIS directory has not been changed. 

1 KIS directory has been changed. 

Bits 7 — 15 Index to start of FIS from start of sector 

Core address of KIS directory 

File combination (zero if file not locked) 

File clock (used for releasing FIS after a period of no activity) 



| B.2 FILE RECORD BLOCK STRUCTURE 



The file record block (FRB) structure, located on mass memory, is composed of zero or more FRBs 
for each file (Figure B-2). Information to/from this structure is obtained via five parameters of the 
file's FIS (see Section B.1.3, words 3, 4, 5, 6, and 14): 



FRBFSA 

NRLFRB 

FRBLSA 

FRBNIX 

FRBSIZ 



is the sector address of the first FRB. 

is the number of records stored in the last FRB. 

is the sector address of the last FRB. 

is the index to the next available location in FRBLSA. 

is the file record block size. 
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FRBFSA 



FRBSIZ 



FRB 



NUMREC 



FRBLSA 
FRBNIX 



FRB 



NUMREC 



RECORD; 



FRB 



NRLFRB 



Figure B-2. File Record Block Structure 



B.2.1 FILE RECORD BLOCK 

An FRB of FRBSIZ sectors is created on mass memory whenever space is needed to store a new 
record. Its sector address is given either by the FIS (if it is the first FRB in a file) or by a previously 
allocated FRB. The size of an FRB, FRBSIZ, is specified by the computation of: 

r it 

3 + MAXRL 



Where: 



96 



MAXRL is the maximum record length of any record to be stored in the file. 



The block is composed of: 

o A three -word header containing: 

-The sector address of the last FRB (a zero indicates the first FRB) 

-The sector address of the next FRB (a zero indicates there are no more FRBs for this 
file) 

-The number of records stored in this FRB (a zero indicates that this is the last FRB and 
reference should be made to NRLFRB) 

9 Zero or more variable or fixed length records 



I Where fx~| is the least integer greater than or equal to x. 
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There are also three other FIS parameters, NRLFRB, FRBLSA, and FRBNIX, which give the number 
of records stored in the last FRB, the sector address of the last FRB and the index to the next available 
location in the last FRB respectively, of each file. 

| B.2.2 FILE RECORD 

A file record, or simply a record, of variable or fixed length is stored/retrieved into an FRB whenever 
a legal file request is given. Its length, variable or fixed, depends on the type of file: not indexed- 
linked or indexed -linked with or without FIFO linking. Its access depends on the type of file: indexed 
or not indexed. In general, a record is composed of: 

• A header word containing: 

-The total length of the record in bits through 14 

-The removed flag in bit 15 (the record has been removed from the file if bit 15 is one) 

• A two-word record pointer if the file is indexed-linked 

• Zero or more data words 

The total record length is given by: 
RL = 1 + NRPW + NDW 

Where: RL is the total record length. 

NRPW is the number of record pointer words (zero if not indexed-linked, two if 
indexed-linked). 

NDW is the number of data words. 

If the record is an extra record created by the File Manager to reserve space for storage of a 
subsequent FIFO -linked record, the header word will contain $8000 and no useful information will 
have been stored in the remainder of the record. The length of this record will be specified by FIFORL 
in the associated file's FIS. 



-1 = File removed 



Index-ordered 
pointer 



Length of record 



SECTOR A DDR 



STARTING WORD OF RCD 



DATA 



Points to next 
linked record 



B.3 KEY INFORMATION SEGMENT STRUCTURE 

The key information segment (KIS) structure, located on mass memory, is composed of: 

• One KIS directory 

• Zero or more KIS blocks for each file with a key defined area (see Figure B-3) 
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Information to/from this structure is obtained via five parameters of the file's FIS (words 7 through 
11): 



KIDSEC is the KIS directory's sector address. 

KIDSIZ is the KIS directory's size in sectors. 

KIBSIZ is the KIS block's size in sectors. 

KEYLTH is the key length. 

NUMEKV is the number of expected key values. 



KIS DIRECTORY 



FIRST KIS BLOCK 



KIDSIZ 



FOUR-WORD 
HEADER 
















| 







KIS BLOCK 
POINTER 

KIS BLOCK 
POINTER 

KIS BLOCK 
POINTER 


1 




NO. OF KISs 






























iTH KIS BLOCK 


















| 














NO. OF KISs 












KISj 














LAST KIS BLOCK 



























NO. OF KISs 











KIS OVERFLOW BLOCK 







NO. OF KISs 



Figure B-3. Key Information Segment Structure 
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I B.3.1 KEY INFORMATION SEGMENT DIRECTORY 

The KIS directory of KIDSIZ sectors is created on mass memory whenever a file is defined to have a 
key (i.e. , indexed). Its sector address is given by the parameter KIDSEC. The size of the KIS 
directory, KIDSIZ, is specified by the computation of 

[(4 + SRNEKV)/96)] 

Where: SRNEKV is the square root of the number of expected key values (see Section 3. 1.2). 

The directory is composed of a four-word header, containing: 



Word 


Mnemonic 





KIDCLK 


1 


NUMKD3 


2 


KIBFSA 


3 


KIBLSA 



Description 
KIS directory clock 
Number of KIS blocks 
First sector address of linked KIS blocks 
Last sector address of linked KIS blocks 



and up to KIBSIZ *96-4 KIS block pointers. Utilizing the given key value to produce a scatter code, 
each KIS block pointer contains a one -word sector address of a KIS block with a scatter code 
corresponding to the pointer's relative position in the KIS directory. If a KIS block pointer is zero, 
there is no KIS block for that particular scatter code. 



| B.3.2 KEY INFORMATION SEGMENT BLOCK 

A KIS block of KIBSIZ is created on mass memory whenever space is needed to store a file's record 
with a new key value. Its sector address is given by the corresponding KIS block pointer in the KIS 
directory of the file. The size of a KIS block, KIBSIZ , is specified by the computation of 



3 + (2 • NUMPTR + KEYLTH) • SRNEKV 



96 

Where: NUMPTR is the number of record pointers in each KIS. The value of NUMPTR is one 

for a LIFO linked or unlinked file. The value is two for a FIFO linked file. 

KEYLTH is the key length (in words). 

SRNEKV is the square root of the number of expected key values. 
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The block is composed of: 



A three-word header containing: 

-The sector address of the KIS block allocated before this one (a zero indicates the first 
KIS block) 

-The sector address of the first KIS overflow block (a zero indicates there are no KIS 
overflow blocks) 

-The number of KISs in the KIS block 

Up to I (KIBSIZ • 96 - 3)/(2 • NUMPTR + KEYLTH)! KISs 



NOTE 

An indexed-ordered file will cause each KIS block to be 
ordered by key value. The ith KIS block will contain key 
values in the range: 

NUMEKV (5Sii) <KEyvAL * NUMEKV (sSra) 



Where: NUMEKV is the number of expected key values. 
NKISB is the number of KIS blocks. 

KEYVAL is the key value. 



B. 3.2.1 KEY INFORMATION SEGMENT OVERFLOW BLOCK 

A KIS overflow block, KIBSIZ, is created on mass memory whenever a KIS block becomes filled, 
either because the number of expected key values was exceeded or the key values do not scatter 
uniformly. Its sector address is given by either its KIS block or by a previously allocated KIS 
overflow block. The block has the same format as a KIS block and is composed of: 

o A three -word heading containing: 

-The sector address of the KIS block allocated before this one. 

-The sector address of the next KIS overflow block (a zero indicates there are no more 
KIS overflow blocks) 

-The number of KISs in the KIS overflow block 

o Up to [(KIBSIZ • 96 - 3)/(2 • NUMPTR + KEYLTH)J KISs 
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In an indexed-ordered file, which is not indexed-linked, KIS blocks other than the first and last will not 
have overflow blocks. The first KIS block will have associated overflow blocks only if one or more 
records with negative key values are stored. The last KIS block will have associated overflow blocks 
only if one or more records with key values exceeding NUMEKV are stored. If overflow blocks are 
created for an indexed-ordered file, the order of the KISs with respect to key value is maintained in 
the KIS blocks and the KIS overflow blocks. 



| B.3.3 KEY INFORMATION SEGMENT 

A KIS of 2 • NUMPTR + KEYLTH words is stored into a KIS block whenever a legal indexed file request 
is given to store a record with a new key value. Its access is achieved by searching the proper KIS 
block. A KIS for a LIFO-linked file record is composed of: 

• A record pointer that points to the last record stored using the same key value 
o A KEYLTH word array containing the key value 

A KIS for a FIFO-linked file record is composed of: 

• A record pointer that points to the first record stored using the same key value 

• A record pointer that points to the last record stored using the same key value 
o A KEYLTH word array containing the key value 



| B.3.4 ALLOCATION OF SPACE WITHIN THE KEY INFORMATION STRUCTURE 

The File Manager is designed so that the size of the KIS directory is dependent on the number of 
expected key values, NUMEKV. We have seen that 



NWHSD = [sRNEKV+4] . 
I 96 I 



96 



2 
For values of NUMEKV less than or equal to 92 ( =8464), 96 words (one sector) are used as the KIS 

directory. For NUMEKV values between 8,465 and 32,767, the KIS directory has a length of 192 words 

or two sectors. The hash code technique for scattering the key values into the KIS blocks is as follows: 



Let 



{KEYVAL . ; i = 1, 2, 3, . . . KEYLTH} 
(i) 



be the set of words comprising the key values for a given record. Let NEKISD equal the number of 
entries in the KIS directory (either 92 or 188), then H, the hash code for the record, is computed as 



H 



KEYLTH 

KV.YVAl. 

(i) 



V^ KEYVAL. 



i = 1 



(mod NEKISD) 
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EXAMPLE: 

Suppose a file is indexed with a key of location code (let KEYLTH = 2 and NUMEKV = 10, 000) and a 
record is to be stored with the location code LJ11 ($ = a hexadecimal number), then the key value in 
ASCII is: 



KEYVAL(l) = 4C4A 



16 



KEYVAL(2) =3131 



16 



then 



H = 



KEYLTH 

E 

i = 1 



KEYVAL 



(i) 



(mod NEKISD) 



E 



KEYVAL. 



(i) 



(mod 188) 



7D7B 



16 



(mod 188) 



= 32,123 (mod 188) = 16 

If the number of actual key values exceeds 8,464, the value of NUMEKV must also exceed 8,464 so that 
192 words (two sectors) will be used for the KIS directory; thus minimizing the number of KIS overflow 
blocks. Fewer KIS overflow blocks implies fewer mass-memory accesses in retrieving a record from 
the file. 

On the other hand, if the actual number of key values is small and the estimate, NUMEKV, exceeds 
8,464, the full 192 words will be used needlessly for the KIS directory; taking up 96 extra words of 
core each time the KIS directory is read in from mass memory. (The KIS directory for a given file 
is in core whenever an indexed file request is made for that file.) 

In addition, the value of NUMEKV helps to determine the length of the KIS blocks since 

N NUMEKV I = SRNEKV 

is the number of entries in each KIS block. Thus, too large a value of NUMEKV would result in 
unnecessarily long KIS blocks. Too small a value of NUMEKV results in KIS blocks that are too short, 
causing the creation of KIS overflow blocks. See Figures B-l and B-2 for examples of key information 
segment structures dependent on the relationship between the number of expected key values and the 
number of actual key values. 
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STORAGE REQUIREMENTS FOR FILE STRUCTURE 



Cl 



^m^j^n.i^-:.^^:^^u^tugfl^g,^''^A t j.-^- 



In this section, the equations for minimum/maximum storage limits are given so a particular file 
structure's storage requirements may be approximated. An example illustrates the calculation of the 
minimum/maximum storage limits. Finally, the equations are derived from the definition of the file 
structure given in Appendix B. 



C.l STORAGE LIMIT EQUATIONS 



C.I .1 DEFINITIONS 

Mnemonic 



MAXRL 
SRNEKV 

KEYLTH 

RL 

NR 

NWF S 

NWFj 

NWF 

MIN 

NWF MAX 

NF 

nf 

NWFS 

NUMPTR 



Description 

Maximum record length of ith file 

Square root of the expected number of records with different key values (NUMEKV) 
of ith file 

Key length of ith file 

Length of record in ith file 

Number of records in ith file. Note that the number of records in a FIFO-linked file 
includes an extra record for each key stored 

Number of words in ith sequential file 

Number of words in ith indexed file 

Minimum number of words in ith file 

Maximum number of words in ith file 

Number of defined files 

Number of defined, but not released, files 

Number of words in the file structure 

Number of pointers in each KIS for an indexed file 
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I C.1.2 ASSUMPTIONS 

In some cases the storage limit equations are approximations that give a minimum and maximum range 
for the file structure. In other cases an exact computation of the file structure is given. 

| For storage efficiency, the maximum record length should be an integer multiple of the 
record length (RL). Furthermore, the maximum record length should be of the form: 

96 • m - 3 

Where: m is a positive integer. Relaxation of these restrictions may be investigated via 

| Section C.3.3.3. 

For calculation convenience the record length is assumed to be constant for any particular file. If 
this assumption is not true for a file, an average record length may be used. However, caution must 
be used so that this average record length does not violate any of the assumptions and restrictions on 
which the file structure is based. 



C.I. 3 SUMMARY OF STORAGE LIMIT EQUATIONS 

From the derivations in Section C.3 and with the assumptions from Section C.1.2. 

1. The number of words in the file record blocks is: 

NWFRB- - (MAXRL + 3, . [^Ji| 

2. The minimum storage limit for an indexed file is: 

NWF,„ xT * (t^§7 JL ~)( RL • NR) + SRNEKV 2 (KEYLTH + 2 . NUMPTR) 
MIN \MAXRL + 95/ \ / 

+ 4 • SRNEKV + 4 

3. The maximum storage limit for an indexed file is: 

(MAXRL + 3 \ / \ 2 

MAXRL A RL ' NR ) + MAXRL + SRNEKV (KEYLTH + 2 . NUMPTR 

+ SRNEKV(95 • KEYLTH + 190 • NUMPTR + 99) + 9507 

4. The minimum storage limit for the file structure is: 

nf 

9fi • NF V 
NWFS * 96 + ° + > NWF lmr 

17 ^ MIN 

i = 1 
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5. The maximum storage limit for the file structure is: 

nf 

NWF 

MAX 



NWFS * 96 + 96(N f" 16) + Y NWF 

17 Z. ] 



i = 1 



C.2 EXAMPLE OF MINIMUM/MAXIMUM STORAGE LIMIT CALCULATIONS 

The following is a hypothetical file structure 



Where: 



NF = nf = 2 (one non-indexed and one indexed file) 



File 1 contains 


MAXRL 


93 words 




RL 


31 words 




NR 


1880 records 


File 2 contains 


MAXRL 


93 words 




RL 


93 words 




NR 


1880 records 




KEYLTH 


8 words 




SRNEKV 


50 words 




NUMPTR 


1 word 


NWFRB_ = NWFRB' „ 





(1) 



(1) 



= <^ rl + Mmaxrl| 

[ 1880 . 31] 
I 93 I 



= 96 

= 60,192 
'MAXRL 



NWF 2: 

MIN(2) V MAXRL 



/MAXRL + 98\ 
\ MAXRL + 95/ 



RL • NR + SRNEKV (KEYLTH + 2 • NUMPTR) 



+ 4 • SRNEKV + 4 



/93 + 98\ 
\93 + 95/ 



(93 • 1880) + 50 (8 + 2 • 1) + 4(50) + 4 
> 217,834 words 
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NWF 



/MAXRL + 3\ 
y MAXRL / 



lVTAXT? T + ^\ 2 

< i ivi^Axvx. — o_^ (RL # NR) + MAXRL + SRNEKV (KEYLTH + 2 • NUMPTR) 



MAX(2) \ MAXRL 

+ SRNEKV (95 • KEYLTH + 190 • NUMPTR + 99) + 9507 



(rirh- 



1880) + 93+50 (8 + 2 • 1) + 50 (95 • 8 + 190 • 1 + 99) 



NWFS 



NWFS 



+ 9507 
< 282,530 



nf 



96 • NF 



* 96 + "",„""" + y NWF 



17 



MIN 



i = 1 



96 • 2 

^ 96+ — + NWF + NWF 

17 MIN(l) MIN(2) 



* 277,151 words 



nf 

96(NF + 16) V 
^ 96 + — k ~tz + 2, NVJF 



17 



MAX 



i = 1 



< 96 + 6 ( + 6 ' + NWF + NWF 

17 MAX(l) MAX(2) 



343,078 words 



Since the absolute minimum storage requirement (NWFS ) for this data structure would be: 



nf 



NWFS 



AM 



= 1 RL i 



NR. 



i = 1 



= RL • NR + RL • NR 
112 2 



= 31 • 1880 + 93 • 1880 
= 233,120 words 



The extra file storage needed for this example would be between 19% and 47% of the absolute minimum 
storage requirement. 
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C.3 DERIVATION OF STORAGE LIMIT EQUATIONS 



C.3.1 DEFINITIONS 

To the definitions given 

Mnemonic 
NWFISD 
FIDSIZ 
NWFISB MIN 
NWFISBmax 

Frosiz 

NFISB 

NFFISB 

NWFIS 

FRBSIZ 

NWFRB 

NRFRB 

NFRB 

NWFRB MIN 

NWFRB MAX 

NWFRB' 

NWKISD MIN 

KIDSIZ 

NWKISBmjn 

NWKISBj 

NWKISB 

KffiSIZ 

NKISB 

NWFISB 

NWFRB. 
1 

NWKISD, 



>MAX 



in Sections of C. 1. 1, the following are added: 

Description 
Number of words in the FIS directory 
FIS directory size in sectors 
Minimum number of words in FIS blocks 
Maximum number of words in FIS blocks 
FIS block size in sectors 
Number of FIS blocks 
Number of FISs in one FIS block 
Number of words in a FIS 

FRB size in sectors (see Section B.2) of the ith file 
Number of words in a FRB of ith file 
Number of records in a FRB of the ith file 
Number of file record blocks in the ith file 
Minimum number of words in FRBs of the ith file 
Maximum number of words in FRBs of the ith file 
Desirable number of words in FRBs of the ith file 
Minimum number of words in KIS directory of the ith file 
Maximum number of words in KIS directory of the ith file 
KIS directory size in sectors (see Section B.3) of the ith file 
Minimum number of words in KIS blocks of the ith file 
Maximum number of words in KIS blocks of the ith file 
Number of words in a KIS block of the ith file 
KIS block size in sectors of the ith file 
Number of KIS blocks in the ith file 
Number of words in FIS blocks 
Number of words in FRBs of the ith file 
Number of words in KIS directory of the ith file 
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Mnemonic 
NWKISBj 
NKKISBj 
SRNEKV 
NUMAKV 



Description 
Number of words in KIS blocks of the ith file 
Number of KISs in one KIS block for the ith file 
L/NUMEKV I 
Number of actual key values. 



| C.3.2 INTEGER FUNCTION THEORY 

If x is any real number, then 

[xj = the greatest integer less than or equal to x 
fx^ = the least integer greater than or equal to x 

Furthermore, it is noted that 

x - 1 < [x] £ x <z [~x~| < x + 1 

and 

+ m - 1 



fcH^^J 



where n and m are positive integers. 



| C.3.3 COMPUTATIONS 

Computations are carried out to find minimum/maximum storage limit equations for the following, 
which is expressed as a function of a file's parameters: 

File information segment directory 

File information segment blocks 

File record blocks for the ith file 

Key information segment directory for the ith file 

Key information segment blocks for the ith file 
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C.3.3.1 COMPUTATION FOR FILE INFORMATION SEGMENT DIRECTORY 



Computations are carried out for the storage size of the FIS directory. Note that NWFISD is a File 
Manager parameter and is defined to be 96. 



NWFISD = 96 



C.3.3.2 COMPUTATIONS FOR FILE INFORMATION SEGMENT BLOCKS 
The number of words in all FIS blocks is computed as follows: 
NWFISB = 288 • NFISB 



= 288 



= 288 



= 288 



= 288 



NWFISB 



288 



r_NF_-i 

NFFISBl 



NF 



I NWFISB - 1 1 
L NWFIS J 



NWFIS 

NF 



I 288 - 1 1 
L 16 J 



NF 



1 287 j 
L16J 



NF 
17 



C.3.3.3 COMPUTATIONS FOR FILE RECORD BLOCKS 

Computations are carried out for three cases: the minimum, maximum, and desirable maximum 
storage limits for the file record blocks of the ith file. The results are obtained from the following 
information: 



From Section B„3: 

Since there are 96 words per sector: 



FRBSIZ 



f 3 + MAXRLl = | 3 + 



MAXRL + 95 



96 



NWFRB = FRBSIZ • 96 



If it is assumed that the record length is 

constant for any particular file then 

(from Section B . 2) : NRFRB 



NWFRB -3 
RL 
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Note that if the record length is not constant for any particular file, an average record length may be 
used, as long as there is a large number of records in the file. 



By definition: 



NFRB 



NR 



NRFRB 



MINIMUM LIMIT 



NWFRB 



MIN 



= NWFRB • NFRB 



= NWFRB 



> NWFRB 



= NWFRB 



^ NWFRB 



|-_nh_1 

I NRFRB | 



NR 



NRFRB 
NR 



I NWFRB - 3 I 
L RL J 



RL 
NR 



NWFRB -3 



RL 



/ NWFRB V„ T XT „ V 
a (NWFRB-3 ) (RL - NR) 

\ + NWFRB - 3 J 



= 1 + 



= 1 + 



NWFRB 
3 



FRBSIZ 



• 96 - 3/ 



(RL • NR) 

(RL • NR) 



1 + 



13 + MAXRL + 95| n 

L 86 J' 96 - 3 



(RL • NR) 



NWFRB 



* 1 + 



MIN 



3 + MAXRL 
96 



+ 95 \ 



(RL • NR) 



96-3 



1 + 



MAXRL 



+ 95 y 



(RL • NR) 



MAXRL + 98 mr XT „ V 
2 MAXRL + 95 (RL ' NR) 
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MAXIMUM LIMIT 



NWFRB 



MAX 



= NWFRB • NFRB 



NWFRB 



= NWFRB 



£ NWFRB 



I NRFRB I 

I NR + NRFRB - 1 I 
L NRFRB J 

( NR + NRFRB - l \ 
NRFRB / 



nwfrWJSLiI + A 



= NWFRB 



= NWFRB 



^ NWFRB 



\NRFRB 

NR - 1 
INWFRB - 3 1 

NR -1 



+ H 



[ "NWFRB - RL - 21 



RL 

NR - 1 



/ NWFRB - RL - 2\ 



+ 1' 



+ 1' 



- NWFRB Y * L J™-J +*' 

^ NWFRB - RL - 2 

/ NWFRB 



\ NWFRB -RL 
RL + 2 



-) 



■(■• 
■('• 



NWFRB - RL 
RL + 2 



FRBSIZ • 96 - RL 



(RL • NR - RL) + NWFRB 
(RL • NR - RL) + NWFRB 

NR - RL) + FRBSIZ • 96 



-) 



Ti) <kl • 



RL + 2 



} 



I 1 3 + MAXRL + 95 1 ~~ ~~ J 

\ L % J-96-RL-2/ 



,t. t \m r, T x |3 + MAXRL + 95 I 
(RL • NR - RL) + L ^ J 



= 11 + 



RL + 2 



[~3 + MAXRL ] 
I 96 I 



(RL • NR - RL) + 



96 - RL - 2, 



h 



MAXRL + 95 



96 



96 
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1 + 



= 1 + 



RL + 2 



/ 3 + MAXRL\ 
V 9 6 ) 



96 
RL 



96 - RL - 2 



■f 



mT XT „ „ TX , 3 + MAXRL + 95 , n „ 
(RL • NR - RL) +( — ]• 96 



-)• 



( x + maxrlI'-rl) 111 - • NR - RL > + MAXRL + 98 



NWFRB 



MAX 



„ / MAXR L +3 \ m „ „„ „ TV „»„„,,. 

S (MAXRL + 1 - RLJ < RL • NR " RL > + MAXRL + 98 



DESIRABLE MAXIMUM LIMIT 

The maximum limit provides for the likelihood of an extremely bad choice for the record length 
parameter (RL). However, if this parameter is chosen carefully, storage will be conserved and a 
more desirable maximum limit can be computed and used to approximate the storage requirement. 

The record length should be chosen such that the term 

NWFRB - 3 
RL 

is (or is slightly less than) an integer. This implies that the record length is a factor of (NWFRB - 3) , 
or 

RL • n = NWFRB - 3 

= FRBSIZ -96-3 



I 3 + MAXRL + 95 I 

L ii J' 96 " 3 

f3 + MAXRLl „„ 

I m 1' 96 " 3 



where n is a positive integer. 

If the maximum record length 
(MAXRL) is of the form: 

where m is a positive integer, 
then 



MAXRL = 96 • m - 3 

RL • n = 96 • m - 3 
= MAXRL 
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Thus, if the record length is a factor of the maximum length, storage space is conserved and the 
following desirable number of words can be utilized: 

NWFRB 1 = (MAXRL + 3) • NFRB 



(MAXRL + 3) 



NR 



FRBSIZ -96-3 



RL 



= (MAXRL + 3) 



(MAXRL + 3) 



NR 



|i- 



MAXRL 



96 



96-3 



RL 



[ NR • RL ] 
I MAXRL I 



C.3.3.4 COMPUTATIONS FOR KIS DIRECTORY 

The number of words in the KIS directory is the number of sectors in the KIS directory, KIDSIZ, 
multiplied by 96. 

NWKISD = KIDSIZ • 96 

The number of sectors in the directory must be large enough to accommodate four header words plus 
one word for a pointer to each KIS block needed for the file. 

The number of KIS blocks needed for the file is NKISB, thus: 



KIDSIZ 



|l~| andN WK ISD =[i-|-l. 9 e 



The File Manager is designed so that the number of KISs in each KIS block is equal to the number of 
KIS blocks; that is, 



NKKISB 



= NKISB 



Also by design of 
the File Manager, 



NUMEKV - NKISB • NKKISB 

= NKISB 2 



or, 



NKISB - [ yNUMEKV J = SRNEKV 
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Therefore, 



But, 



Therefore, 



NWKISD 



SRNEKV 



4 + SRNEKV 



96 



■1- 



96 



96 



r 



SRNEKV 1 1 4 + SRNEKV + 95 1 ^ 99 + SRNEKV 



96 



I 



96 



96 



NWKISD- xT = SRNEKV + 4 £ NWKISD <; SRNEKV + 99 

MIN 



- NWKISD 



MAX 



C.3.3.5 COMPUTATIONS FOR KEY INFORMATION SEGMENT BLOCKS 

= [" 3 + (KE YLTH + 2 • NUMPTR) • SRNEKV" ! 
I 96 I 



From Section B.4, NWKISB 



96 



Thus, the minimum length for a KIS block occurs when both KEYLTH and NUMEKV are small and the 
file is not indexed-linked. 



Suppose 



then, 



KEYLTH - 1 

NUMPTR = 1 

NUMEKV = 2 

NWKISB = 96 



The maximum length for a KIS block occurs when KEYLTH and NUMEKV are assigned their maximum 
values and the file is FIFO index-linked. 



If 



then, 



KEYLTH = 63 

NUMPTR = 2 

NUMEKV = 32,767 

NWKISB = 12,000 



The expected number of KIS blocks is dependent on the expected number of key values (NUMEKV) and 
on the actual number of key values (NUMAKV). The relationship for the case NUMAKV = NUMEKV is 
g shown in Table C-l. The number of KIS overflow blocks depends on how NUMEKV relates to the actual 
number of key values and on whether or not the key values scatter uniformly. 
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Table C-l. Number of KIS Blocks as a Function of Number of 
Expected Key Values 



' 










LENGTH OF 












KIS BLOCK 












FOR FILE 








NEKISD = 




WITH 


SRNEKV = 






MAXIMUM 




KEYLTH = 4 


NUMBER OF KISs 




EXPECTED 


NUMBER OF 


LENGTH 


AND NO 


IN EACH KIS 


NUMAKV = 


NUMBER OF 


ENTRIES IN 


OF KIS 


INDEX- 


BLOCK 


NUMEKV 1" 


KIS BLOCKS 


KIS DIRECTORY 


DIRECTORY 


LINKING 


1 


1 


1 


92 


96 


96 


1 


2 


2 


92 


96 


96 


1 


3 


3 


92 


96 


96 


9 


91 


91 


92 


96 


96 


9 


92 


92 


92 


96 


96 


9 


93 


92 


92 


96 


96 


9 


94 


92 


92 


96 


96 


92 


8,464 


92 


92 


96 


384 


92 


8,465 


93 


188 


192 


384 


92 

• 


8,466 


94 


188 

• 


192 


384 


92 


8,559 


187 


188 


192 


384 


92 


8,560 


188 


188 


192 


384 


92 


8,561 


188 


188 


192 


384 


181 


32,766 


188 


188 


192 


768 


181 


32,767 


188 


188 


192 


768 


tNUMAKV = Number of actual key values 








NUMEKV = Number of expected key values 
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In the following discussion we will assume uniform scattering. Let NUMAKV be the number of actual 
key values and NEKISD be the maximum number of entries in the KIS directory, then, NUMAKV/ 
NEKISD is the number of expected key values with the same scatter code. Since SRNEKV KISs can 
appear in one KIS block, when NUMAKV/NEKISD is less than or equal to SRNEKV, the number of KIS 
overflow blocks is zero. Let NEKISO denote the number of KIS overflow blocks. Then for NUMAKV/ 
NEKISD <; SRNEKV, we have 

NEKISO = 



For NUMAKV/NEKISD > SRNEKV, we have 

NUMAKV 



NEKISO = 



ft 



NEKISD • SRNEKV 



■J-)- 



NEKISD + NUMAKV (mod NEKISD) 



Note that NUMAKV/NEKISD is the expected number of keys per scatter code; SRNEKV is the number of 
keys per KIS block; and NEKISD is the number of scatter codes. Also, when NUMAKV/NEKISD is less 
than SRNEKV, there will be one KIS block for each of the NEKISD scatter codes. 

| See Table C-2 for some examples of the relationship between the expected number of KIS overflow 
blocks and key values and the actual number of key values. 



Table C-2. Expected Number of KIS Overflow Blocks as Related to 
Expected and Actual Key Values 









SRNEKV = 


EXPECTED 


EXPECTED 








NUMBER OF KEYS 


NUMBER OF 


NUMBER OF KIS 


NUMAKV 


NUMEKV 


NEKISD 


PER KIS BLOCK 


KIS BLOCKS 


OVERFLOW BLOCKS 


1 


1 


92 


1 


1 





92 


92 


92 


9 


92 





8,464 


8,464 


92 


92 


92 





32,767 


32,767 


188 


181 


188 





100 


1 


92 


1 


92 


8 


100 


16 


92 


4 


92 


8 


100 


8,464 


92 


92 


92 





9,000 


1 


92 


1 


92 


8,908 


9,000 


8,464 


92 


9 


92 


92 


9,000 


32,767 


188 


181 


188 
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C.3.4 EQUATIONS 

The equations for calculating the minimum/maximum storage limits for non-indexed and indexed files, 
as well as the total minimum storage limits for the file structure are given. 



C.3.4.1 STORAGE LIMITS FOR NON-INDEXED FILE 



F rom Appendix B : 

and from Section C.3.3.3 
(assuming the desired 
maximum limit): 



NWF = NWFRB. 
S 1 



NWF_ = (MAXRL + 3) 



fNR • RL | 
| MAXRL I 



C.3.4.2 STORAGE LIMITS FOR INDEXED FILE 



From Appendix B: 

and from Section C.3.3.3 
(assuming the desired 
maximum limit) and 
Sections C.3.3.4 and 
C.3.3.5 (assuming 
NUMAKV = NUMEKV): 



NWF T = NWFRB + NWFISD. + NWKISB. 
I 1 1 1 



, 96 + SRNEKV • 96 • 

fSRNEKV • (KEYLTH + 2 • NUMPTR) + 3] 
I 96 I 



C.3.4.3 TOTAL STORAGE LIMITS FOR FILE STRUCTURE 



From Appendix B: 



and from Sections 
C.3.3.1 and C.3.3.2: 



nf 



NWFS = NWFISD + NWFISB + S NWF. 



i = 1 
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ACCESS RATES FOR FILE STRUCTURE D 1 



wMWdM^yajjMMjaMfrJHWiui^^ 



(Refer to Section 4 for definition of symbols.) 



D.l ACCESS EQUATIONS FOR STORAGE/RETRIEVAL METHODS 

The access equations for the sequential, indexed, and direct storage/retrieval methods, as well as the 
initial and terminal usage of the files are calculated using the definition of the file structure given in 
Appendix B. 



D.l.l ACCESSES FOR SEQUENTIAL METHOD 



STORE 

A sequential store requires one access for storing the record, plus one extra access for storing a file 
record block pointer, if the record is the first record in the file record block. Thus, to store all the 
records in a file record block, one more store than the total number of records in the file record 
block is required. The number of accesses for storing a sequential record is minimized when all the 
records in a given file record block are stored in loop. Within such a loop, the number of accesses for 
storing a sequential record is computed as follows: 



NA 



NRFRB + 1 
SS NRFRB 

1 



= 1 + 



= 1 + 



NRFRB 
1 



1 NWFRB -3 1 
L RL J 



= 1 + * 



FRBSIZ -96-3 



= 1 + 



RL 

1 



[ 3 + MAXRL] 



96 ■• 96 - 3 



RL. 
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If the assumptions in Section B. 2. 2 are true, then 

1 



NA 



SS 



= 1 + 



| MAXRL I 

L RL J 



NA 



SS 



= 1 + 



RL 



MAXRL 



Note that if the record length (RL) equals the maximum record length (MAXRL), two accesses are 
required for each sequential store. However, as the limit of RL/MAXRL approaches zero, only one 
access is required. 



RETRIEVE 



A sequential retrieve requires one access for retrieving the next sequential record, plus one extra 
access if the record is being removed. Therefore the number of accesses for the next sequential 
retrieve is given by: 



NA. 



NSR 



1 + f(ro) 



Note that the average number of accesses to retrieve any record in a sequential file is given by: 



NA 



ASR 



= — + f(ro) 



| D.I. 2 ACCESSES FOR THE INDEXED METHOD 



STORE 



An indexed store requires one access for retrieving the desired key information segment block and one 
access to update it with the proper information, plus the number of accesses required for a sequential 
store (Section D. 1.1) to store the record. Therefore the number of accesses for storing one indexed 
record as a part of a loop to store all the indexed records in one file record block is given by 



NA 



IS 



= 3 + 



RL 



MAXRL 
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RETRIEVE 



An indexed retrieve requires one access for retrieving the desired key information segment block and 
one access for retrieving the record, plus two extra accesses if the record is being removed. 
Therefore the number of accesses for an indexed retrieve is given by: 



NA. 



IR 



= 2 + 2 • f(ro) 



D.1.3 ACCESSES FOR THE DIRECT METHOD 



STORE 



A direct store requires one access for updating the record. Therefore the number of accesses for a 
direct store is given by: 



NA 



DS 



= 1 



RETRIEVE 



A direct retrieve requires one access for retrieving the record, plus one extra access if the record is 
being removed. Therefore the number of accesses for a direct retrieve is given by: 



NA 



DR 



= 1 + f (ro) 



D.1.4 ACCESSES DUE TO THE INITIAL USAGE OF A FILE 



NON -INDEXED 



If there have been no accesses via file requests of the file structure for a period of time, the next 
access is designated an initial usage of the file structure. This requires one extra access to read in 
the file information segment directory. Furthermore, if there have been no accesses via file requests 
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of a particular file for a period of time, the next access to this file is designated an initial usage of the 
file. Assuming that the file numbers scatter uniformly, the number of FISs with the same scatter 
code is given by: 



NFISSS 



NF 



/ NWFISD - 2 



| Since NWFISD equals 96 (see Section C.3.3.1), then 

[ ~NFl 
| 47 I 



NFISSS 



On the average, the expected number of FISs to be accessed to find the FIS corresponding to a given 
file number is given by 







r "i 




i- -i 


1. |~nf"| 

2 ' 1 47 1 


< 


1 ^ NF 

2 ' 47 


= 


NF 
94 



This gives an upper bound on the number of file information segment blocks that must be accessed to 
read in a given file information segment. 

Therefore, the expected number of accesses for an initial usage of a non-indexed file is given by: 



NA „ s: 1 + 
IUNF 



IS1 



INDEXED 



If there have been no accesses via indexed file requests of a particular indexed file for a period of time, 
the next indexed access to this file is designated an initial indexed usage of the file. This requires one 
extra access to read in the key information segment directory. Furthermore, if the indexed file has not 
been accessed for a period of time by non-indexed methods, extra accesses are also required as in the 
non-indexed case. Therefore, the number of accesses for an initial usage of an indexed file is given by: 



NA, 



IUIF 



2 + 



[NF] 
I 94 1 
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Note: In this section it has been assumed that the user has not followed the file access time optimization 
procedure described in Section 4.3. If the user has followed this optimization procedure, all the files 
with one scatter code will be stored in one FIS block. If the procedure has been followed and if the 
number of files is less than or equal to 



( 



Maximum number of scatter codes \ t / Maximum number of FISs that can be 

represented in FIS directory ) \ contained in one FIS 



= 94 • 18 = 1,598 
then the expression 



f*l 



in the equations of this section can be replaced by the value 1. 



D.1.5 ACCESSES DUE TO THE TERMINAL USAGE OF A FILE 



NON -INDEXED 

If the file structure is not accessed for a period of time, one extra access is required to write out the 
file information segment directory (if it has changed). Furthermore, if a particular file is not used for 
a period of time, one extra access is required to write out the file information segment (if it has 
changed). Therefore the number of accesses for the terminal usage of a non-indexed file is given by 



TUNF 



INDEXED 

If a particular indexed file is not accessed for a period of time, one extra access is required to write 
out the key information segment directory (if it has changed). Furthermore, if the indexed file has not 
been accessed by non-indexed methods, extra accesses are also required as in the non-indexed case. 
Therefore the number of accesses for the terminal usage of an indexed file is given by: 



NA mTTTT , £ 3 
TUIF 
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I D.2 DISK/DRUM AVERAGE TRANSFER RATE 



| D.2.1 DISK AVERAGE TRANSFER RATE 



The average transfer rate of the 853 disk is quite complex when word addressing is utilized. However, 
approximations can be made if the number of words that are to be read or written is small (e.g. , 
RL < 93). With this assumption, the average transfer rate for a disk read or write is given by *: 



TR « SEEK + LAT + LAT 

DKR DK DK 



/ RL - l \ 
V 9 6 / 




and 



TR 



DKW 



SEEK + LAT + LAT DK + 2 • LAT^ 



/ RL - l \ 
\ 96 / 



110 +13 + 25 + 2 



•»ftr) 




Note that the above assumes that the software overhead is negligible. 



| D.2. 2 DRUM AVERAGE TRANSFER RATE 



The average transfer rate of the 1751 drum is the sum of the average latency and the word transfer 
times. Therefore: 



TR_ _ _ = LAT__ _ + TWR_ _ _ • RL 

DM DM DM 



TR = 8 + .008 • RL milliseconds 

DM 



*The derivation of these approximations is not proven here because of space considerations. For 
larger records (RL > 93), the transfer rates may be modestly or substantially increased. 
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FIS, FRB, KIS, AND FILE SPACE POOL DUMPS Eg 



^»>«^«h^al«^;^^ 



One sequential and one indexed file are defined in the FORTRAN code in Figure E-l. Three records 
are stored into the sequential file, file number 256. Each data word contains the record number for 
each sequential record. Four records are stored into the indexed file, file number 97. Each data word 
of the record with the key value AA^g contains the value A^g and each data word of the record with the 
key value BB 16 contains the value B^g. Similarly, the record with the key value CC^g is filled with 
CjgS and the record with the key value DD^g is filled with D^gS. 

PROGRAM EXAflPL 

DIMENSION IREQBF-Cl2>-,IRECBF-CT3> 1 I0BUF{Sfi},IRECPT-C2} 
C SET UP SEQUENTIAL FILE/3 RECORDS 
C DEFINE FILE NUMBER 25b {=$100} 

IFLNUM=25b 
C LOGICAL UNIT A IS THE DISK 

LU=fl 
C TO OPTIMIZE USE OF FILE SPACE IN FILE BLOCKS-, LET MAXRL=13-C=Tb*l-3> 

MAXRL=13 

CALL DEFFIL-CIFLNUM-,MAXRL-,LU-,IREdBF-,IRE<2IDJ 
C CHECK FOR ERRORS 

IF -CIREflID.LT.0} GO TO 5000 
C SET UP INDEXED FILE/4 RECORDS 
C DEFINE FILE NUMBER 1? 

IFLNUM=^7 

MAXRL=13 

CALL DEFFIL {IFLNUM-,MAXRL-,LU,IRE<2BF-.IRE<2ID> 
C CHECK FOR ERRORS 

IF -CIREQID.lt. 0? GO TO 5000 
C DEFINE FILE 17 AS AN INDEXED FILE WITH A 0NE-U0RD KEY AND 
C 400 EXPECTED KEY VALUES 

KEYLTH=1 

NUMEKV=400 

CALL DEFIDX-CIFLNUMtNUMEKViKEYLTHiLUiIREUBFiIREAID} 
C CHECK FOR ERRORS 

IF -CIREi3ID.lt. 0> GO TO 5000 
C STORE 3 RECORDS INTO SEQUENTIAL FILE -CFILE NUMBER 25b> 

IFLNUM=2Sb 
C EACH RECORD HAS 31 U0RDS 

DO 100 IREC=l-«3 
C LET CONTENTS OF EACH DATA UORD OF THE RECORD BE THE RECORD NUMBER. 
C NOTICE THAT NOTHING IS STORED IN THE FIRST UORD OF A REC0RD-.AS THIS 

Figure E-l. FORTRAN Code Example (Sheet 1) 
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C WORD IS RESERVED FOR USE BY THE FILE MANAGER. 

DO SD IU0RD=Ei31 
SD IRECBF-CIL)ORD>=IREC 

CALL STOSEO-tIFLNUn-,IRECPT-,IRECBFi31 1 IREQBF-,IRE(3ID} 
C CHECK FOR ERRORS 

IF CIREfllD.LT.O} GO TO 5000 
100 CONTINUE 
C STORE FOUR RECORDS INTO FILE 17i UITH KEYS=SA A-,$BB-,$CC-. AND 5DD-. 
C RESPECTIVELY. LET EACH DATA WORD OF THE RECORD UITH KEY VALUE SAA 
C CONTAIN THE VALUE $A. LET EACH DATA WORD OF THE RECORD UITH KEY 
C VALUE $BB CONTAIN THE VALUE $B. SIMILARLY-, THE RECORD UITH KEY 

C VALUE $CC IS TO BE FILLED UITH $C*S-, AND THE RECORD UITH KEY VALUE 
C SDD IS TO BE FILLED UITH $D*S. 
C INITIALIZE KEY VALUE AND DATA UORD VALUE. 
KEYVAL=SAA 
IDATA= $A 
IFLNUf1=T7 
DO EDO IREC=li4 
DO ISO IU0RD=S-.T3 
ISO IRECBF-CIUORD}=IDATA 

CALL STOIDX {IFLNUM -,KEYVAL-,IRECPT-,IRECBF-, c 13.,IREl3BF-,IREt3ID3- 
C CHECK FOR ERRORS 

IF CIREOID.LT.O} GO TO SOOD 
C INCREMENT KEY VALUE AND DATA UORD VALUE 
KEYVAL=KEYVAL+$11 
IDATA=IDATA+1 
EDO CONTINUE 
GO TO 5010 
C PRINT ERROR MESSAGE 
SOOO CALL SETBFR-CI0BUF-.S8} 

URITE {M-ibOOO} IFLNUM-.IREOID 
5010 CONTINUE 

CALL RELESE-CEXAMPL} 
bOOO FORMAT-tSHFILE il5-.fiH ERROR $-,$4} 
END 



Figure E-l. FORTRAN Code Example (Sheet 2) 
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After execution of the program, the FIS directory is dumped (as shown in Figure E-2). The FILMGR 

SYSDAT core location FIDSEC is dumped to determine the location of the FIS directory. The value of 

FIDSEC is 2EA 1 „, therefore mass memory sector 2EA is dumped to obtain the FIS directory. 
16 16 

The first word of the FIS directory contains 2EB, g which points to the first FIS block. The scatter code 
for file 256 is 256 (mod 47) = 21. The 21st two-word entry in the FIS directory is 2EB 16 , 1, indicating 
that the FIS for file 256 is to be found in sector 2EB, fi , word 1. The scatter code for file 97 is 
97 (mod 47) =3. The third entry in the FIS directory indicates that the FIS for file 97 is to be found at 
sector 2EB 16 , word H]_g. 
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The 288-word FIS block containing the FIS for file 256 and the FIS for file 97 is shown in Figure E-3. 
The FIS header word contains a zero that indicates there are no more FIS blocks. The FIS for file 256 



is found in words 1„„ through 10, of the FIS block. 
16 lb 



Words 11 through 20 contain the FIS for file 97. 
16 16 
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FIS HEADER WORD ► 

FIS' FOR FILE 256 ► 
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Figure E-3. FIS Block Example 
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Words 3,4, and 5 of the FIS for file 256 indicate that the file contents for this file are in sector 2EF 16 . 
Section 2EF-,- is shown in Figure E-4. The three -word FRB header indicates that this is the first FRB 
and that there are" no more FRBs. The remainder of the sector contains the three records stored in the 
file and the first word of each record contains the record length. 
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Figure E-4. FRB Example Sequential File 



File 97 is an indexed file. To find a record corresponding to a given key value, the KIS directory must 
be examined. Word 7 of the FIS for file 97 indicates that the KIS directory is located at sector 2EE 16 
(refer to Figure E-3). The KIS directory is shown in Figure E-5. The directory header shows that 
there are four linked KIS blocks, the first in sector 2F1 16 and the last in sector 2F7 lfi . 
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Figure E-5. KIS Directory for File 97, A Sample File 
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Figure E-6 shows four entries in the KIS directory and the key value, scatter code, and KIS block 
pointer for each entry. The first KIS directory entry points to the KIS block with scatter code zero, as 
opposed to the first FIS directory entry, which points to the first FIS with scatter code one. 
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VALUE 


K = 
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OF KEY 
VALUE 
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CODE = 
K(MOD 92) 
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(FROM FIGURE 
D-5) 
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Figure E-6. Key Values, Scatter Codes, and Corresponding KIS Pointers 



The KIS block for key value AA 16 is located in sector 2F1 16 , as shown in Figure E-7. The KIS block 
header indicates that this is the first KIS block and that there are no KIS overflow blocks. There is one 
KIS in this KIS block, which is located in words 3 through 5 of the sector. It shows that the record with 
I key value AA 16 is stored in sector 2F0, starting at word 3. The record is also shown in Figure E-7. 
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I After execution of the program shown in Figure E-l, the file space list and pool are dumped. In the 
system used in this example, the file space list is composed of a block of 1-sector, 2-sector, and 
3-sector segments. When dumped, the file space list is empty. The SYSDAT FILMGR word FSPOOL 
contains 2F8 16 ; the first three words of this sector are shown below: 



02F8 



0000 0000 3FF2 



A diagram of the file space pool is shown in Figure E-9. 
file space pool example shown in Figure 2-2. 



This figure may be compared with the other 



FSPOOL 



3FF2 



16 



POOL BLOCK 

OF 3FF2 16 -SECTOR 

SEGMENTS 



Figure E-9. File Space Pool 



The first zero pointer indicates that there are no other segments of this length in the pool. The second 
zero pointer indicates that there are no pool blocks of segments having a greater length. The third 
word indicates that the length of this segment is 3FF2 16 sectors. 
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FILE STRUCTURE ILLUSTRATIONS 



The following illustrations of the file structure are given: 



F.l FILE STRUCTURE FOR STORAGE/RETRIEVAL METHODS 

The flow logic for sequential, indexed, and direct storage/retrieval are illustrated in Figure F-l. 
Note that all three share a common path, i.e. , the flow logic through the FIS directory and the FIS 
blocks. Once the file information segment is found, each proceeds on its separate path until the record 
is retrieved. 



F.2 FILE STRUCTURE FOR INDEXED-LINKED WITH LIFO-LINKING 

The file structure for indexed-linked with UFO-linking is illustrated in Figure F-2. Note that records 
2, 6, and 8 have the same key value (B), records 1 and 5 have the same key value (C), records 3 and 4 
have the same key value (D), and record 7 has a unique key value (A). 



F.3 FILE STRUCTURE FOR INDEXED-ORDERED 

The file structure for indexed-ordered files is illustrated in Figure F-3. This example assumes that 
the number of expected key values is nine; therefore, there are three KIS blocks with each KIS block 
having three key information segments. In the figure five records have been stored. Note that each 
key information segment is stored in a particular KIS block and is ordered within that block by its key 
value. 



39520600 D F-l 



FIS 
DIRECTORY 



FTS 
BLOCK 



FTS 
BLOCK 



FIS 
POINTER 












FIS OF 
iTH FILE 


1 




1 







KTS 
DIRECTORY 



KTS 
BLOCK 



KIS BLOCK 
POINTER 



J 



KIS OF 

jTH RECORD 



FRB 



FRB 



FRB 




_.l 




1 



jTH RECORD 
OF iTH FILE 



► Common flow logic 

► Sequential flow logic 



Notes: 1. 

2. 

3 . ► Indexed flow logic 

4. ► Direct flow logic 

5. Repeated logic 



Figure F-l. File Structure Flow Logic for Storage/Retrieval Methods 
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Figure F-2. File Structure for Indexed- Linked File with LIFO-Linking 
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Figure F-3. File Structure for Indexed-Ordered File 
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FILE MANAGER ERROR MESSAGE 



G 1 



»"-■■ 'J'"-"-'.n v-' 1 - 



/^fjifri 



3Z 



PRINTING ON 






COMMENT DEVICE 


MEANING 


RECOVERY 


F.M. ERROR 1 


Irrecoverable mass memory 


The user may autoload and 




error occurred while space 


purge all system files, then 




was being returned to the 


reload files from a user 




space pool. This error may 


written backup as described 




result in invalid space pool 


in Section 2. 




threads and/or file space 






being lost to the File Manager. 





Note also that the File Manager returns error information to the user program via reqind. 
status word is defined in Figure 2-1. 
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Examples of 4-6 
File structure D-l 



Combination, file 

Example of 3-39 
Uniqueness of 2-6 



Data word 2-5 
Define file call (DEFFIL) 3-4 
Define file indexed (DEFIDX) 3-6 
Direct requests. See store direct record and 
retrieve direct record. 

Examples of 3-28 

Storage and retrieval 4-3 
Direct storage 2-2 
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Disk read 4-3 

Disk write 4-3 
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